How-to maintain documentation on Discourse

This document describes how documentation is maintained on Discourse.

Contents:

Introduction

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.

Navigation pane

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>)|

Where:

  • <level> is the indentation level for display;
  • <path> is the path component in https://mir-server.io/docs/<path> URLs;
  • [<name>](<url>) is the Markdown-formatted item to be rendered in the navigation pane.
    It is recommended to use relative, short /t/<number> URLs.

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.

Redirects

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.

Formatting

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.

Headings

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 #heading--name anchor.

Commenting

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.
-->

Versioning


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)

---

Converting content

From Google Docs

The Docs to Markdown extension is a good starting point for content that exists in Google Docs:

https://workspace.google.com/marketplace/app/docs_to_markdown/700168918607

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:

  1. Head on to the tutorial in question,
  2. At the bottom there’s a “Suggest changes” link, follow it to a Discourse post,
  3. Edit the post and take the contents out,
  4. Remove the table at the top and the “Duration:” hints,
  5. Place the content in a new topic under Mir / documentation,
  6. Link the new topic to the “How-to guides” section of the navigation.
  7. 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”.

Resources

There’s more content around this topic available, e.g.:

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 a month ago. Help improve this document in the forum.