Documentation guidelines

Please feel free to modify any of the topics here with updated or more insightful information. If you participate in the snap community and in the forum, you don’t need additional permissions to do that, as these pages are all available for editing in the forum itself. Go ahead and fix that typo, add a section, or even a new page. Others will join in and help finishing what you start, or reorganising it if necessary. Of course, feel free to ask and discuss when appropriate.

Before creating a new topic, please consider whether the content would fit well in an existing one first, and try not to make topics which are too specific, but rather a section inside a more general one.

Please try to make the content pleasant to read, with proper punctuation and capitalisation. Read the documentation before writing something entirely new, to get a feeling for the style. Being terse rather than verbose tends to be a good idea as well, as it forces the writer to focus on the point being made.

Assume you’re explaining something to intelligent readers. People may not have experience on that one subject, but many will have plenty of experience on the larger picture.

If you are adding information about a feature that is still in development, please remember to tag it with with the appropriate version in which it will become valid, in the format “(snapd 2.15+)”, so that readers know when they can start using it.

When you’re in a rush but would like to hint at something that is coming, use “(work in progress)” (lowercase and italics) as the content of the section/example/etc.

Sometimes it’s useful to provide information to documentation editors. For that, add the comment inside a block quote that includes the :construction: 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:

:construction: **NOTE TO EDITORS** :construction:

This note is not visible in the dedicated documentation site.

Have fun, and if you need anything, please get in touch via the forum

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