Content: page or blog post on why your project should be versioned

[agjohnson]

We have information on how to accomplish versioning in our documentation ¹ but we haven't really tried communicating why your project should be versioned, or describing best practices when versioning your project. This is a core feature for us, so seems like some place we really should be providing guidance to projects.

Some suggested points would include:

• Differences between versioned and unversioned documentation
• When you should consider versioning your documentation
• Benefits to versioning/illustration of problems with unversioned documentation
• Pitfalls to avoid when versioning
• Examples of versioned documentation
• How to accomplish this with Read the Docs (point to our docs here)
  • Our versioning doc ¹ does touch on this, but could use some guide content

Footnotes

1. https://docs.readthedocs.io/en/latest/versions.html ↩ ↩²

[agjohnson]

Thinking more, perhaps both are warranted here.

A website page could lean more towards marketing language and tone when describing the need for versions and describing Read the Docs features for versioning.

A blog post might also do this, but perhaps with more guidance and pointers to resources.

[humitos]

(my comment from Slack's conversation)

This is something I really want to have in our docs. I may have more comfortable writing a blog post than years ago now (that was my first post I think and it wasn't the correct to start blogging at the company)
Ideally, as this topic is opinionated, I'd say that we should discuss the TOC first (sections) all together and decide what's the message we want to communicate. Having that will help anyone writing the post to fill the gaps. Besides, it will help with review since we won't be discussing the direction of it nor the technique (3.x branches OR tags, etc)

[agjohnson]

There is enough content here that I think we can split this up into three parts.

• Site page: This is the one that I'd like to author soon. It's the argument for why to version, and doesn't need to touch on technical aspects much yet. It's opinionated and makes a case for the problems of unversioned documentation and why versioning solves these issues.

• Documentation: we have some docs here, but I'd agree that we'd benefit from making our versioning page a bit more opinionated. It doesn't need to argue the same points as our website, and following patterns from other changes, our docs should stick to more technical details that we're not going to cover in our marketing focus

• Blog post: I'm not sure exact what this is, but some mix of the two? Perhaps a case study in enabling versions on a project is a good fit here. We can still be opinionated and can illustrate the concept by example.