Long term support architecture
jedahan opened this issue · comments
As the lifetime of the Pi project extends, the number of products the documentation will need to support will grow. I've thought about this for a while, but once I saw Project Rewrite felt comfortable opening it up for discussion.
For software libraries, and apis, I've seen drop-down's to choose major versions that effectively support people working with different versions. See https://docs.rs/clap/latest/clap/ or https://reactnative.dev/docs/getting-started as examples.
A drop-down for that rendered the latest version of the docs for that model would
- reduce the need to weave warnings, exceptions, and gotchas within a page
- keep pis from reaching landfills due to missing support materials (e.g. when underlying OS or boot changes how to configure a pi)
- reduce support burden when new OS or product changes are made
This would require a substantial change to how docs are built, but I think the benefits would be worth it.
What are your thoughts? Pinging @aallan
For software libraries, and apis, I've seen drop-down's to choose major versions that effectively support people working with different versions.
That's fine for single "things" that have specific versions, and a documentation release to go with that version. But the Raspberry Pi documentation isn't around a single piece of software or hardware. It isn't necessarily versioned. OS releases can sometimes make major changes to the documentation, but there are other factors like hardware releases, or the introduction of entirely new classes of product, that change things more fundamentally.
Documentation is not on a per-model basis. It never has been. These days it would be hard to really define what "a model" is when we now have multiple core product lines.
As a consequence we would have to maintain multiple versions (snapshots) of the documentation site, and I don't see that reducing support burden. Especially as these snapshots would be taken at more or less arbitrary places, with documentation for some products okay, while for others the documentation wouldn't be in a good state. It's really unclear to me what would spawn a new snapshot of the site that had to be maintained, versus a change (or set of changes) that wouldn't.
Right now if you want a previous revision of the documentation site you can check it out from Github, and build the site locally. As many users would find that difficult I'm currently toying with methods to automate that, and let users do it inside Github Codespaces, so that they could revert to previous versions of the site automagically, and have it all "just work" in the browser.
Right now effort is going towards rewriting the current documentation (aka Project Rewrite) around the idea that there is more than one core product — most of the mess is there because we had a single product and the design of the documentation is around supporting that and only that — in a more narrative style, with a better split between feature and task-led documentation.
Alongside this we have developer effort is currently directed towards our PDF toolchain which needs overhauled due to technical debt building up, and some fragility introduced by third-party dependencies. After that ships there are other things already on the schedule.
Then maybe after that, we can think about archival revisions. Sorry.