Feel free to modify any documentation topic with updated or more insightful information. If you already participate in the snap community, you don’t need additional permissions; pages are freely editable within the forum itself. Of course, feel free to ask and discuss when appropriate.

Documentation consistency is vital, which is why we’re listing some guidelines below, but don’t let this formality put you off - just start writing and editing. If something is inconsistent, we’ll fix it.

As Voltaire wrote, “Perfect is the enemy of good,” and we’d rather have inconsistent documentation we can easily fix than non-existent documentation we can’t.

Style and language

One of our biggest challenges is accommodating an audience with a huge variation in experience, from beginners exploring the snap command, through snap creators experimenting with snapcraft.yaml, to experts harnessing the API and deploying snaps across thousands of IoT devices.

Consequently, we try to:

pitch the writing and editing appropriately for the subject

write inclusively and assume very little prior knowledge of the reader

link or explain phrases, acronyms and concepts that may be unfamiliar, and if unsure, err on the side of caution

Inline code

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

For instance, to create `$SNAP_DATA`:

Hyperlinks

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

[visible text](url)

The visible text is what will appear in the documentation. The url is either the full URL of a link outside of the documentation, or the topic reference without the domain name for a page within the documentation.

To link to https://forum.snapcraft.io/t/snapcraft-overview/8940, for example, you would use the following:

For more details, see [Snapcraft overview](/t/snapcraft-overview/8940).

The Discourse topic identifier, 8940 in the above example, is optional and can be omitted.

Anchors

Discourse Markdown does not support anchor links to a position within the same page or another document.

However, you can use standard HTML within Markdown, which means we can manually add HTML anchor elements that can be linked to.

The recommended way to create anchors is using heading elements with an ID. The ID needs to have heading-- as a prefix:

<h3 id='heading--myanchor'>Link to me</h3>

To create an anchor called base-snap, for example, enter the following into your document:

<h3 id='heading--base-snap'>Base snaps</h3>

This can now be linked to with the following:

/t/snapcraft-overview#base-snap

Use HTML sparingly as it can make the raw text difficult to read.

Notes and admonishments

It’s occasionally worth highlighting important notes or warnings outside of the main body of text. These are called admonishments.

There is no current standard for admonishments with Discourse Markdown. We have hijacked Markdown’s block-quote syntax for this purpose, starting an admonishment with a >, often followed by a symbol, and then the text itself:

For example:

Note: Layouts can only help within a snap’s environment.

The Markdown for the above is as follows:

> ⓘ **Note**: Layouts can only help _within_ a snap's environment.

An admonishment type is typically either ‘Note’ or ‘Warning’ or omitted completely.

Comments

Sometimes it’s useful to provide information to documentation editors. For that, add the comment inside a block quote that includes the icon. These will be excluded from the dedicated documentation web site, but will be visible in the forum when editing. It may look similar to this:

[quote]
:construction: **NOTE TO EDITORS** :construction:
This note is not visible in the dedicated documentation site.
[/quote]

Foldouts

When a page contains a lot of extraneous information such as walkthroughs or reference tables, a foldout can be used. This will create a collapsed header which, when clicked, will expand to display all the content below it.

Foldout syntax in Discourse uses two sets of square brackets with an open and close details tag that acts as the title in the opening brackets:

[details=Manually create a network on a 10.x.x.x subnet]
If you try to run `lxd init` on a system that is connected to a network with a `10.x.x.x` subnet,
then the final step of the Iinit* may fail with the following error:
[/details]

The above will appear as follows:

Manually create a network on a 10.x.x.x subnet

If you try to run lxd init on a system that is connected to a network with a10.x.x.x subnet, then the final step of the Iinit* may fail with the following error:

Images

Most of our documentation covers command line tools, editing and developing. However, if relevant, we highly encourage the use of images. An image should be easier to understand than text, reinforce concepts being discussed in the topic, and break the monotony of words following words.

When making images:

do not crop your images too closely to allow 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 topic you’re editing, or uploaded via the toolbar icon. It can also be helpful to edit the description field of an image link after uploading: