These are the guidelines for helping to improve MicroStack documentation. For an overview of how contributions work see the Documentation contributions page.
- Writing style
- Line length
- Source format
Documentation consistency in terms of writing style is vital for a good user experience.
Here are some general tips:
- define acronyms and concepts–don’t assume others are familiar with the subject
- use a spell checker
- resist being overly formal
- resist being overly verbose
- verify links and examples
- do not repeat what’s been covered in other posts - use hyperlinks
- do not use emojis
We adhere to the Canonical Documentation Style Guide.
Discourse honours the line length in its editor. Therefore, ensure that a paragraph does not take on a jagged appearance (long lines mixed with short lines). Use common sense when inserting line breaks so the resulting text looks good to the reader.
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.
Individual elements are now explained. Some formatting can be achieved in more than one way. Kindly use the methods described in order to maintain consistency throughout the documentation.
## Subheading within a document ### Subheading of a subheading
We don’t use the top-level heading (
# Heading) as the topic title serves this purpose.
Headings and subheadings should use sentence case, which means the first letter is the only one capitalised. Proper nouns and acronyms are exceptions.
For a bullet list, use a hyphen ( - ). Sub-lists will use an hyphen indented at least 2 spaces:
We (mostly) adhere to the Ubuntu style guide, for example: - we use British English (en-GB): - the _ise_ suffix in preference to _ize_
For a numbered list, use
1. to precede each item. The numbering will be rendered automatically. One benefit is that it’s simple to insert new items:
1. This is the first item 1. This is the second 1. This is the third 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.
An example table:
|heading 1||heading 2||heading 3|
It is produced by the following markdown:
heading 1 | heading 2 | heading 3 -|-|- cloud | user | pass type | access | key
Use colons for horizontal alignment:
|heading 1||heading 2||heading 3|
heading 1 | heading 2 | heading 3 :-|:-:|-: left | centered | right type | access | key
Left-aligned is the default, and does not need to be stated.
The number of dashes has no effect on the final result.
Enclose a code block with three backticks and include the type of code:
```yaml name: gimp version: '2.10.8' summary: GNU Image Manipulation Program ```
The most common code types are:
text. The last is like a miscellaneous type. It is often used to display command output and does not highlight anything.
text type is usually the best choice as the other types often appear to highlight things randomly from the reader’s perspective.
Do separate command input blocks from command output blocks. For input, do not use a command line prompt (e.g.
#) and precede the output block with some kind of intelligent message:
Use a backtick to mark inline commands and other literals. For instance, to create
For instance, to create `$SNAP_DATA`:
For links to internal files or external URLs, use the following format:
For internal pages the full URL is not necessary. The below will work for, say,
For linking to headers (see next section ‘Anchors’), this can be used:
Or, if within the same page:
To link to a header within the same page or in another page you will need to use HTML tags. Importantly, this will also create header links on the published page so that they can be used universally on the internet.
For example, to create a link to the (second-level) destination header of “Adding clouds” edit the header on the destination page (
clouds here) so it changes from this:
## Adding clouds
<a href="#heading--adding-clouds"><h3 id="heading--adding-clouds">Adding clouds</h3></a>
As shown above, base the anchor name (
heading--adding-clouds) on the destination header (
Adding clouds), even if this is not strictly required. This is for consistency and logic.
Within the same Discourse instance, this can now be linked to with the following URL:
Or, if within the same page:
External to the Discourse instance (on the internet), a full URL will be needed but with the
#heading--adding-clouds portion affixed to the end.
Avoid altering the names of existing anchors as doing so may break existing links to it. It is not obvious what other pages are linking to it.
To highlight something, you can use admonishment. Admonishments are self-contained snippets that are not part of the main flow of the document. The wording is correct if the admonishment can be understood independently of the body copy and removing it does not impact readers’ understanding of the surrounding text.
Admonishments in Discourse use BBtext markup syntax. Using
[/note] draws a box around some text.
[note type="note" status="Note"] An informative note. This box is dark blue. [/note]
An informative note. This box is dark blue.
The status header gives a title. You can omit it:
[note type="note"] A note without a title. [/note]
Its output becomes:
A note without a title.
type parameter is optional, but recommended:
[note] A note that only uses default settings. [/note]
A note that only uses default settings.
type parameter changes how it is presented to the reader:
The below examples are produced using type and status combinations of ‘caution/Warning’, ‘positive/High score’, and ‘negative/Game over’, respectively:
Here be dragons.
Please try again.
Hyperlinks cannot be word-wrapped within admonishments. Doing so will not format the links.
When a page contains a lot of extraneous information, such as software code or file contents, a foldout can be used. This will create a collapsed header, which, when clicked, will expand to display all the content below it.
[details=This is the visible header] This text is completely hidden. The reader clicks the header to reveal its contents. [/details]
The above will produce:
This is the visible header
This text is completely hidden.
The reader clicks the header to reveal its contents.
An image should be easier to understand than text, reinforce concepts being discussed in the topic, and break the monotony of a long stream of paragraphs.
When making images:
- do not crop your images too aggressively; add a little extra to provide context
- use a resolution high enough to make text legible and work with high-DPI displays
- a wide aspect ratio fits better with the width of the rendered documentation
- save with lossless compression, such as PNG for screenshots (JPG is acceptable for photos)
Images can be simply dragged and dropped into the edit field, or uploaded (local device or a public URL) via the toolbar icon. It can be helpful to edit the description field of an image link after uploading:
![description of image](<location>)
To resize images based on pixels or a percentage of pixels use the following syntax:
![description of image]|200x200](<location>) ![description of image]|200x200,50%](<location>) ![description of image]|64x64](<location>)
These images are produced with the following:
![venus|316x318](upload://3rvhVhtSJ59epM9sLj86qHMVfiL.jpeg) ![venus|316x318,50%](upload://3rvhVhtSJ59epM9sLj86qHMVfiL.jpeg) ![venus|100x101](upload://3rvhVhtSJ59epM9sLj86qHMVfiL.jpeg)