Creating and editing MicroK8s documentation

The MicroK8s website has a docs category which displays documentation indirectly from special topics in the discuss.kubernetes.io MicroK8s category
These topics are published as wiki topics, meaning they can be edited by anyone with enough reputation on the Kubernetes discourse. There is a link at the bottom of each docs page which will take you to the corresponding discourse topic.

Editing in Discourse markdown

If you are familiar with Markdown syntax, editing the pages should be straightforward, though there are a few idiosyncracies which you should be aware of:

  • linebreaks: Unlike most common Markdown, discourse respects ALL linebreaks. Don’t bother neatening up paragraphs by adding linebreaks at 79 characters unless it is really important for the output
  • images: there are limitations involved in adding images. It is better to link these to an external source rather than try uploading them when they are more of them than just a single screenshot or inline graphic
  • emojii: try not to use them - they look fine in discourse but often translate badly or at the wrong size in the published docs

There is more detailed explanation further down this page

Some guidance for writing

Documentation consistency in terms of writing style is vital for a good user experience.

Here are some general tips:

  • use a spell checker (set to en-GB!)
  • resist being overly formal
  • resist being overly verbose
  • verify links and examples
  • don’t repeat what’s been covered in other posts - use links
  • don’t make too many assumptions - explain, link or reference things the average reader may not know

We adhere to the Canonical Documentation Style Guide. In particular:

  • we use British English (en-GB), for example:
  • the ise suffix in preference to ize (capitalise rather than capitalize)
  • our instead of or (as in colour and color)
  • license as a verb, licence as a noun
  • catalogue rather than catalog
  • dates take the format 1 January 2013, 1-2 January 2013 and 1 January - 2 February 2013

Adding pages

Adding a new page to the documentation involves:

  • Creating a new topic in discourse, correctly labelled
  • Publishing it as a wiki page
  • Adding the page to the navigation

Some of these steps can only be achieved by people with special permissions or a very high status on the kubernetes.io discourse. If you want to add a page but don’t have the relevant permissions, you can still create the topic and then ask one of the MicroK8s crew (e.g. @evilnick or @kjackal) to add it for you.

  1. Create the topic

Just click on the Discourse New Topic button like you would for any other post. Under the categories, it must go under General Discussions / microk8s, and should add the docs tag too.

Screenshot from 2020-11-12 12-06-47

  1. Write the page!

Once you have entered all the text, checked it looks good in the preview and clicked on the create topic button, you should check it turned in to a Wiki page:

category example screenshot

Topics posted to the category are turned into a Wiki by default, but in case there was an issue, it is useful to check. You will find the Wiki options under “show more> post admin actions” (the elipsis at the bottom of the post). If the options say “ Remove Wiki” (as in the above image) then it’s working.

  1. Add it to the navigation

to add the page to the navigation, you will need the “short URL” of the page you created. This includes the critical topic id number, but omits the site part. E.g. the short URL for the main index page https://discuss.kubernetes.io/t/introduction-to-microk8s/11243/ is simply /t/introduction-to-microk8s/11243/.

Use the short URL to create a link in the ‘Navigation’ section of the page. For example:

  1. * [Getting started](/t/introduction-to-microk8s/11243)

The full URL MUST be added to the special table which begins:

  1. ## URLs
  3. [details=Mapping table]
  4. | Topic | Path |
  5. | -- | -- |

This table controls the re-written URL of the docs page generated from the topic. Without an entry here, your page will not be processed as a docs page. Pay particular attention to the format and the separators for the table - don’t miss any! E.g.:

  1. | full_url | /docs/name-of-page |
  2. | https://discuss.kubernetes.io/t/get-in-touch/11261 | /docs/get-in-touch |

Please be thoughtful when adding pages - it really isn’t a good idea to just randomly add pages of things you think would be useful or interesting. In order for people to be able to find and reference documentation, it should be created to fit into the hierarchy of pages which already exist. Most of the time this is fairly obvious - a page about an add-on should be linked from the current add-ons page. If you are unsure of where the page should go, or don’t think it fits into any of the current sections in the navigation, please have a discussion about it first!

Docs Markdown, everything you wanted to know

Markdown format

Documentation is written in the CommonMark Markdown format supported by Discourse.
Mostly, you don’t need to worry about the syntax. You can simply use the style toolbar in the Discourse topic editing window to mark the elements you need.
If you don’t find what you are looking for in these topics, you can always copy from an existing post (TIP: you can view the raw content of a page by just editing the url in your browser, and replacing the /t/topic-name/ part with /raw/ instead. For example: https://discuss.kubernetes.io/raw/11243 instead of https://discuss.kubernetes.io/t/introduction-to-microk8s/11243.

Headings and titles

  1. ## Subheading within a document
  2. ### Subheading of a subheading

We don’t use the top-level heading (# Heading) as the topic title is used for this.

Headings and subheadings should use sentence case, which means the first letter is the only one capitalised. Proper nouns and acronyms are exceptions.

Lists

For a bullet (unordered) list, use a hyphen ( - ). Sub-lists will use an hyphen indented at least 2 spaces:

  1. We (mostly) adhere to the Ubuntu style guide, for example:
  2. - we use British English (en-GB):
  3.   - the _ise_ suffix in preference to _ize_

For a numbered list, use 1. to precede each item. The numbering will be rendered automatically, which makes it easy to insert new items:

  1. 1. This is the first item
  2. 1. This is the second
  3. 1. This is the third
  4.     1. This is a sub-list

The indent here needs to be at least 3 spaces.
Unless a list item is particularly long (which should be avoided) and includes punctuation, don’t end the item with a full stop. If one item needs a full stop, add one to all the items.

Tables

For example:

animaltypecolour
doglabyellow
horseshirebay

It is produced by the following markdown:

  1. |animal|type|colour|
  2. |-|-|-|
  3. |dog | lab | yellow |
  4. | horse | shire | bay |

Use colons for horizontal alignment:

heading 1heading 2heading 3
leftcenteredright
typeaccesskey

The markdown:

  1. heading 1 | heading 2 | heading 3
  2. :-|:-:|-:
  3. left | centered | right
  4. type | access | key

Left-aligned is the default, and does not need to be stated.

Code blocks

Enclose a code block with three backticks and include the type of code:

  1. ```yaml
  2. name: gimp
  3. version: '2.10.8'
  4. summary: GNU Image Manipulation Program
  5. ```

The most common code types are: bash, yaml, json, and text. The last is like a miscellaneous type. It is often used to display command output and does not highlight anything.

Do separate command input blocks from command output blocks. For input, do not use a command line prompt (e.g. $ or #) and precede the output block with some kind of intelligent message:

  1. uname -r

Sample output:

  1. 4.14.151

Inline code

Use a backtick to mark inline commands and other literals. For instance, to create $SNAP_DATA:

  1. For instance, to create `$SNAP_DATA`:

N.B. You will normally have to press the backtick key twice to get a single backtick

For links to internal files or external URLs, use the following format:

  1. [visible text](url)

You can also use an intermediary label and then associated that label with the actual URL (usually at the bottom of the document). This is common in documentation, as often there can be several links to the same URL, and it makes it easier to maintain when updating links:

  1. [visible text][label]
  2. .
  3. .
  4. .
  5. [label]: url

The visible text is what will appear in the documentation.

For internal pages the full URL is not used (important for the navigation links). The below forms will both work for, e.g. https://discuss.kubernetes.io/t/introduction-to-microk8s/11243/:

  1. [Intro](/t/introduction-to-microk8s/11243/)

Or just:

  1. [Intro](/t/11243/)

Comments

Adding comments (which aren’t displayed) to the source may be useful either to create a TODO list, or to explain to future editors of the document why something has bee expressed in a certain way.

  1. <!--
  2. This is better as text than a screenshot as it will look completely different each new version.
  3. -->

A TODO list would normally go at the very top of a document:

  1. <!--
  2. TODO:
  3.  - Update versions for 1.20
  4.  - Update when bug is fixed: https://bugs.launchpad.net/juju/+bug/1797399
  5. -->

Last updated 9 months ago. Help improve this document in the forum.