Keeping old DocC documentation updated

[daveverwer]

We should consider whether/how we will keep versioned documentation up-to-date with future DocC tool changes.

As I have been working on the DocC version switcher, it’s striking switching between DocC documentation generated with the 5.7 beta DocC and the 5.6 stable one. The sidebar is the big issue here, and I know we’re going to re-generate all docs before launching the versioned docs feature, but I think we need to think about the future, as this won’t be the last major change to DocC.

Right now, once a stable version is superseded, we effectively ignore it in terms of building. That works well for builds, and if we ever need to completely reset a package’s compatibility results, we remove build results, causing it to automatically re-build the latest significant versions.

With our feature to keep documentation for old major versions of packages, we should think about how we’d cope with the situation of re-generating all docs for a package, including old major versions. This then leads to being able to do that for multiple/all packages if/when major DocC template changes occur.

There will also come a time when the Xcode versions we use for the iOS documentation builds will go out of date, and we won’t have runners available to generate old versions. There’s probably not much to do here because if there’s a package that can’t be built with any runner we have, it’s almost certainly a dead package, but it’s another point to consider.

I won’t go into potential solutions here, but I wanted to start a discussion, so the issue is on our minds.

[daveverwer]

Just to note, too. It may be that we decide that once documentation for a major version of a package is superseded by a new major version, those docs are never updated again even if DocC changes, and if they break (due to a browser rendering engine change or similar), they stay broken.