How can we reorganize the docs so people don't confuse 'stable' and 'latest' ?

[rfay]

People are always landing on our latest docs, which is usually OK, but those may have behavior changes that have been pulled/committed, but are not in the release people are using. Then they get confused. In a couple of recent cases they actually did PRs against the quickstarts to set them back to the way they are on stable.

Our intent is for them to use the stable docs, which match the current released stable version of DDEV.

I believe we should probably just expose one version of the docs.

However, there's always ongoing improvement to the docs by the community which does not affect behavior change.

How could we switch to using a single exposed version of the docs without losing the ability to update non-destructive docs? Or should be just give up that capability?

[GuySartorelli]

I haven't looked into how the docs site is built/where it pulls from, and I'm still learning the branching strategy here, so I don't know how much of this will be applicable, but here's how we handle this problem in the Silverstripe CMS docs:

• When we have an unstable branch (i.e. next major branch, not yet released but has alpha or beta releases), we add the docs for that branch with a clear banner indicating that the docs are for an unstable version, and with a link to the docs for the most recent stable version
• Docs for upcoming minor releases are simply not published to the docs site
• When a minor release goes stable, the docs for that version are updated
• Docs for any given stable release are available on an appropriate branch, and are pulled from that branch

So for DDEV, if you wanted to do something similar:

• Docs for unreleased changes (i.e. "latest") have a clear banner warning users that the docs include unreleased changes, and a link to the stable docs
• PRs which will be updating docs for current features (e.g. fixing typos or mistakes or what have you) should target the branch the stable docs are pulling from, and get merged up to master from there
  • I'm guessing that branch right now would be v1.17?

[GuySartorelli]

The other option, of course, is to only show the stable docs. I think this might actually be more suitable for this project, as I don't think it's likely there are many people using the latest copy of DDEV. In that case, I'd recommend just going with the second part of what I said above:

PRs which will be updating docs for current features (e.g. fixing typos or mistakes or what have you) should target the branch the stable docs are pulling from, and get merged up to master from there

So docs can be updated as needed for the stable docs, but unreleased features aren't displayed. That does rely on the stable docs being pulled from a branch though, dunno how they're pulled right now.

[rfay]

We use readthedocs.org for this, and it's pretty easy to do all or nothing. It's this simple:

We can add a new version, and we could change "latest" to track a "safe docs" branch, and introduce a hidden version that had master's docs. I think this might be a fairly simple path.

The problem will be how to maintain the "safe docs" branch, and making sure that nothing gets orphaned there.

But docs changes could always go onto master, but when safe go onto safe-docs.

[GuySartorelli]

It's this simple

That doesn't look like "do all or do nothing" - one of those is pointing at a branch, and the other at a specific commit. And there's an edit button which presumably gives you some level of control over that? There's not enough information here for me to really understand what level of control you have.

we could change "latest" to track a "safe docs" branch, and introduce a hidden version that had master's docs. I think this might be a fairly simple path.
But docs changes could always go onto master, but when safe go onto safe-docs.

Sounds like a lot of overhead for you, since you then need to look at every docs change and decide whether to cherry pick it into the docs-specific branch each time.

I'd recommend either splitting docs into their own repo so they're easier to manage in that way, or pointing docs changes (which aren't related to functionality changes) at the safe-docs branch initially, and then if they actually do relate to unreleased code, change the target branch before merging.
But ultimately it depends on how you want to weigh maintenance effort vs risk of "unsafe" docs changes sneaking into safe docs vs chance of safe docs being missed, and only going to master

[rfay]

splitting docs into their own repo

My experience with that is that docs don't properly get updated. I do love having the docs with the code changes.

[GuySartorelli]

That's a fair point, definitely part of the equation.

[stasadev]

Linking this to

• docs: show a warning banner for the latest docs (readthedocs+mkdocs) #5855