Docs moving to maas.io/docs, content to Discourse


#1

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]

#2

What will happen to the issues on https://github.com/canonicalltd/maas-docs/issues?

Where will you track docs issues? Here?

How can any community members help if they are not “trusted”? https://discourse.jujucharms.com/t/documentation-migrated-to-discourse/1274/9

How do you efficiently “blame” docs?


#3

Hi @szeestraten, I’ll try to answer your questions below:

Where will you track docs issues? Here?

Issues with documentation content should now become discussions below the relevant document, or otherwise discussed in this Discourse forum.

What will happen to the issues on https://github.com/canonicalltd/maas-docs/issues?

I’ll go through and triage those issues. If they are issues with content, I will close them and request that they be moved to discussions in this forum, or if they are things that can be fixed elsewhere I’ll file them elsewhere.

How can any community members help if they are not “trusted”? https://discourse.jujucharms.com/t/documentation-migrated-to-discourse/1274/9

If a user does not have permission to edit the main content of a topic, they can instead post a comment requesting that a change be made. The administrators of this platform can tweak the “trust” rules as time goes by depending on what works.

How do you efficiently “blame” docs?

If you have permission, you can view the change history of a post by clicking on the orange pencil icon in the top right (it only shows us if there is any history):

Opens up:


#4

IIt would be best to consolidate all issues in the project page https://bugs.launchpad.net/maas/+filebug


#5

We have now put this change live - the official home of the docs is now https://maas.io/docs, and https://docs.maas.io now redirects there.

The official place to contribute to the content is now on the topics in the docs category.