discussion: how to manage documentation between versions

[yoshuawuyts]

Docs always document a subject. Sometimes the subject introduces breaking changes, and if there are a lot of docs it might take a while to update the docs. An option is to hold off releasing the version until the documentation has been updated, but that might stagnate releases. What would be nice is to have a way of reflecting at which version the subject is; so that the documentation can be updated gradually and transparently without ever needing to block a release.

Another problem that arises is when the documentation has been updated, but people haven't upgraded yet. They might be viewing documentation that doesn't work for their particular version. Features might be introduced in newer versions, and they run into issues. Sometimes people might not be ready to upgrade yet, and need access to older docs - which can be rough if we don't expose copies of them. It would be nice if there was a way to access these older documents - targeting specific version or otherwise.

I know all of this could definitely introduce a slew of complexity; but I think acknowledging this problem exists and exploring possible solutions would be greatly beneficial. Thanks!

---

edit: so tldr:

• can we add a lil note for which version a document is intended
• can we figure out a way to host documentation for multiple versions

[sethvincent]

Oh, yeah. This would definitely be useful.

Possible approach:

Put version in the routes:

/:page/:version

Specify versioned content in contents.json:

{
  "modules": {
    "example": {
      "versions": {
        "1.0.0": "#example markdown",
        "1.1.0": "#example markdown v1.1.0"
      }
    }
  }
}

To get that automated for a collection of modules we may need to do some work on ecosystem-docs to grab the versioned readmes of each module. I wonder if it would be easier to pull that from npm rather than github.