How-to maintain Mir documentation on Discourse
This document describes how Mir documentation is maintained.
- Navigation pane
- Converting content
The Mir and Ubuntu Frame documentation pages are maintained on this Ubuntu Discourse. Each page’s content lives in the first post in a separate discussion thread, with subsequent posts serving as space for discussion about the content.
The entry point is a thread whose content is used as the home page, but includes extra metadata for navigation and redirects (explained below). You can reach this thread by following the “Help improve this document in the forum” at the bottom of the rendered version.
The “Help improve …” link at the bottom of each page will take you to the thread from which the content is sourced.
We maintain a list of tasks to complete in this GitHub Project.
The Navigation table present at the bottom of the home page post describes the navigation structure of the documentation tree. It is rendered as the navigation pane on the documentation site.
Its format is a Markdown table:
## Navigation [details=Navigation] |Level|Path|Navlink| |--|--|--| |<level>|<path>|[<name>](<url>)|
<level>is the indentation level for display;
<path>is the path component in
[<name>](<url>)is the Markdown-formatted item to be rendered in the navigation pane.
It is recommended to use relative, short
If an item is not meant to be a link, but rather an organizational heading, omit
<path> and just use plain text in the Navlink column.
Similar to Navigation, there is a Redirects table, whose purpose is ensuring that once a page is published, its URL will remain valid, even if the content is moved or removed.
The format is a simple table:
## Redirects [details=Mapping table] | Location | Path | |--|--| |/docs/<old path>|<new url>|
Whenever you move the content or remove a page from the documentation site, consider whether it could be bookmarked or indexed in search engines, and if so, add an entry to the Redirects table so that users arriving there are not greeted with a
404 Not Found error.
Content is rendered from Markdown just as it is on Discourse 1. There are a few additional notes that help rendering useful documentation from the content here.
To be able to refer directly to a particular section in documentation, it’s recommended to use HTML headings with an anchor around them, like this:
<a href="#heading--name"><h2 id="heading--name">Name</h2></a> <!-- leave an empty line, too --> Content <a href="#heading--name-subheading"><h3 id="heading--name-subheading">Subheading</h3></a>
When using subheadings, make sure the anchor has the full context, including the parent heading title.
You can then link to them using the
To hide some content that you don’t want rendered, but don’t want to remove (e.g. when refactoring it), just use HTML comments:
<!-- This content is hidden because… It is in need of refactoring. -->
To denote a section of documentation that only applies to a certain version of the software, use a note:
[note status="Version 2.7"] This feature is only available from Mir 2.7 onward [/note]
Version: This feature is only available from Mir version 2.7 onward
Table of Contents
At the top of each document, build a Table of Contents. Unfortunately still manual, but is a pretty simple:
**Contents:** - [Heading title](#heading--title) - [Subheading title](#heading--title-subheading-title) ---
From Google Docs
The Docs to Markdown extension is a good starting point for content that exists in Google Docs:
Since the document may be linked elsewhere, leave the document be and add a link to the new location rather than trashing it.
From Ubuntu Tutorials
To convert from content on tutorials.ubuntu.com:
- Head on to the tutorial in question,
- At the bottom there’s a “Suggest changes” link, follow it to a Discourse post,
- Edit the post and take the contents out,
- Remove the table at the top and the “Duration:” hints,
- Place the content in a new topic under Mir / documentation,
- Link the new topic to the “How-to guides” section of the navigation.
- Replace the content of the tutorial with a link to the new location, including a “This content was moved…” comment.
NB: Most content on there are actually How-to guides in accordance with the Diátaxis Framework3, so place it there rather than under “Tutorials”.
There’s more content around this topic available, e.g.:
- Creating Discourse-based documentation pages
- Editing MAAS documentation
- Docs moving to maas.io/docs, content to Discourse
If you find problems with how the documentation pages are rendered, report a bug on the project’s GitHub page.
1 Discourse markdown reference
2 Vanilla syntax highlighting
3 Diátaxis framework
Last updated 5 months ago. Help improve this document in the forum.