We’ve been working on moving towards handling documentation in a similar model to how it’s handled for snapcraft. That is, documentation content is stored in “wiki” topics in Discourse, which any community member can help to improve, and the documentation website will pull content from these Discourse topics.
Release
About couple of months ago we started migrating the documentation content from the maas-docs repository into the “Docs” category in this discourse site.
The next step will be to release a new section of the maas.io website at maas.io/docs, which will pull its content from topics in the “Docs” category. The old documentation site at docs.maas.io will redirect to maas.io/docs, and the maas-docs repository will be archived. We intend to release this change in the next couple of days.
Editing pages
Once this new system is live, each page of documentation under maas.io/docs will have a link at the bottom saying “Help improve this document in the forum”. This link will take you to the Discourse topic containing the content for that page, which in most cases can be directly edited by any member of this Discourse community. Or alternatively, comments can be added below that topic to discuss any change to the topic post itself.
The index topic
A key piece of this new system is the “index” topic, MAAS Documentation. This page contains the content for the maas.io/docs landing page, as well as the docs section navigation, URL mappings and redirects. This topic cannot be directly edited by the community, but please feel free to add comments below to request any changes.
Versioning and old documentation
The documentation at maas.io/docs will initially describe the current version of MAAS, version 2.6. Documentation for older versions of MAAS can be found at https://old-docs.maas.io/2.5/en/.
Going forward, we will no longer create new documentation pages for new versions of MAAS. Instead, changes between MAAS versions should be mentioned inline in the documentation pages, using note sections - e.g.:
From 2.7: This feature is only avaiable from MAAS 2.7 onwards
[note status=Version 2.7]
This feature is only avaiable from MAAS 2.7 onwards
[/note]
