Suggestion: Adopt a Diátaxis Framework, including non-Canonical-hosted documentation.
- Previous discussion in Ubuntu Discourse: Outdated Documentation
- Adoption by Canonical MAAS team: https://ubuntu.com/blog/moving-toward-diataxis
“Diátaxis Framework” is a fancy name for separating the four types of documentation that have different audiences and different functions: Tutorials, HowTos, Discussion/Explanation, and Reference.
Some of this documentation is hosted on the Wiki, some is on Discourse, some is on readthedocs, some is on YouTube, some is on AskUbuntu, some is upstream, and some is scattered across hundreds of blog posts. Folks are creating lots of documentation; they’re doing much of it other places instead of the Wiki.
The framework suggests that some documentation is appropriate for the Wiki, and some is not.
We can use this framework to prioritize the kinds of documentation that we want for our users, avoid duplicating appropriate documentation that is already hosted elsewhere, and to guide hosting decisions for regular updates.
Example: If a good how-to-install-Ubuntu 20.04 tutorial is on YouTube, then we don’t need to be in a hurry to recreate it in another venue. We might want to ping that creator to upload an updated video for new releases.
Example: If a good discussion/explanation of the features of the Subiquity Installer is located only on one developer’s blog, then we might engage that developer for regular updates (or suggest they copy the post from blog to the Wiki or to Discourse).
I think this kind of framework can eliminate some Wiki Paralysis. You’re not writing a document for all possible users: It’s either a simple checklist for beginners or a lengthy discussion for advanced learners. Separate documents will be easier to maintain, one way of addressing documentation bitrot.
I think it also addresses some of the egad-what-are-we-going-to-do-about-the-huge-old-wiki question. It’s a framework to evaluate what should be in wiki format, what is better hosted non-wiki on other Ubuntu sites, and what is better hosted outside of Ubuntu infrastructure entirely.
There can many bite-sized volunteer tasks, entry points for new volunteers: Update the checklist for XYZ, ping these YouTube creators for the new release, etc.