Contribute to our docs

We warmly welcome community contributions, suggestions, fixes and constructive feedback.

The navigational structure, style, and content of our documentation follows the Diátaxis systematic framework for technical documentation authoring. This splits documentation pages into tutorials, how-to guides, reference material and explanatory text.

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 documentation we can fix than non-existent documentation we can’t.

Open Documentation Academy

The Open Documentation Academy is an initiative led by the documentation team at Canonical to provide help, advice, mentorship, and dozens of different tasks to get started on, within a friendly and encouraging environment.

A key aim of this initiative is to help lower the barrier into successful open-source software contribution, by making documentation into the gateway, and it’s a great way to make your first open source documentation contributions to Ubuntu Core, snap and Snapcraft.

But even if you’re an expert, we want the Academy to be place to share knowledge, a place to get involved with new developments, and somewhere you can ask for help on your own projects.

The best way to get started is with our task list . Take a look, bookmark it, and see our Getting started guide for next steps.

Stay in touch either through the task list, or through one of the following locations:

If you’d like to ask us questions outside of our public forums, feel free to email us at docsacademy@canonical.com.

In addition to the above, we have a weekly Open Documentation Hour starting at 16:00 UTC every Friday. Everyone is welcome, and links and comments can be found on the forum post.

Finally, subscribe to our Documentation event calendar. We’ll expand our Documentation Office Hours schedule and add other events throughout the year.

Agreements

Everyone involved with CODA needs to follow the words and spirit of the Ubuntu Code of Conduct v2.0.

Most of the projects that participate in CODA require that a contributor has signed a Contributor licence agreement, or CLA. Such an agreement will typically grant permission for the project to use a contribution while the contributor retains the copyright and the rights to modify their own work, or use it in other projects.

The Canonical contributor licence agreement is one such CLA. This needs to be signed before a contribution can be considered for inclusion within one of Canonical’s projects. Many GitHub repositories for Canonical projects will automatically check whether a contributor has signed the CLA when a contribution is made.

The cla issue label is used to help identify which tasks require a contributor to have signed a CLA.

Identifying tasks

There is no guarantee a task will be worked on, or that a contributor will complete a task within a specified time. Consequently, you should choose tasks outside the scope of your current cycle, or create tasks from long-standing documentation issues that have yet to be addressed.

To best reflect the entire range of work that documentation requires, we want our task list to be as broad and as diverse as possible, from composition, structure and maintenance, to the tools and frameworks used to generate and publish the final output.

Small tasks, such as replacing outdated terminology, checking for broken links, and ensuring adherence to the Canonical Documentation Style Guide are an ideal place to start. Moderately sized tasks might include converting documentation from one format to another, or migrating the contents of a blog post into the official documentation. But more ambitious tasks are also welcome, such as adding a new How-to guide, restructuring a group of documents, developing new tests and automations.

Creating a task

Tasks are created as new issues on the CODA repository:

https://github.com/canonical/open-documentation-academy/issues/new

  • The title of the task starts with the name of the associated project, such as Snapcraft: or LXD:, followed by a short sentence describing the task.

  • The description of the task should expand upon the title of the task, provide additional context and expectations, and give some indication of the amount of effort required.

  • Include links to any current documentation that may help a contributor research a task and understand a solution.

  • List any prerequisites for completing a task, such as understanding how a certain tool works. Make it clear if a task requires specific domain experience, and also if it’s suitable for anyone without specific experience.

  • Add appropriate labels for size estimations and the type of work required.

Task suggestions

The following are starting suggestions for potential tasks requiring either a small, medium or large amount of work.

Small

Convert a table from using two columns to three columns

A contributor needs only a high level understanding of the project, and of the formatting syntax, to complete this task, and can use what already exists as a template.

Example: Public Cloud: Change table format

Medium

Improve the way a concept is explained

This requires the potential contributor to learn and understand the concept with enough depth that they can improve the way it’s already documented.

Example: Snap: improve interface management documentation

Large

Update an example to use more modern tooling

A contributor will need a good understanding of why an example has become stale, and technically how it might be updated and improved. They will also need to be prepared to change the documentation in unpredictable ways, such as new sections on new tools, and to potentially document the migration from one version of a tool to another.

Example: Snapcraft: Update Java example to use core22

Completing and closing tasks

When a task has been completed to your satisfaction, we’ll ask the contributor whether they would prefer to merge their work into your project themselves, or leave this to the project.

Recognition

After a task has been successfully completed, we’ll give credit to the contributor and share their success in our forum here, on the pages themselves, and in our news updates and release notes.

Documentation source

The documentation for Ubuntu Core is open source and is available at the Ubuntu Core documentation repository on GitHub.

We welcome contributions, suggestions, fixes and constructive feedback from the user community. If you feel something is inaccurate, unclear or broken, you have a number of ways to fix it:

Contributing to our documentation is straightforward. We only require that all contributors sign the Canonical contributor license agreement.

In order to contribute, you will need to set up a GitHub account and a git environment. The Get started with git guide, from the Canonical Open Documentation Academy, is a useful resource for people who are new to contributing using the Ubuntu command line.

The navigational structure, style, and content of our documentation follows the Diátaxis systematic framework for technical documentation. This categorizes the documentation into tutorials, how-to guides, reference material and explanatory text.

Consistency is vital in documentation, which is why we request contributors to follow the style-guide. We also set up the following GitHub actions to run automatically on every pull request raised against our docs repository:

  • Inclusive language check

  • Spellcheck

  • Accessibility check

  • Link check

However, do not let this be a barrier to your contribution. You can still submit contributions to the best of your ability, and if something is inconsistent, we will fix it. We are targeting continuous improvement rather than delayed perfection.

Open Documentation Academy

Our Canonical Open Documentation Academy is a great way to make your first open source documentation contributions to Ubuntu Core, snap and Snapcraft.

The Academy is an initiative led by the documentation team at Canonical to provide help, advice, mentorship, and dozens of different tasks to get started on, within a friendly and encouraging environment.

A key aim of this initiative is to help lower the barrier into successful open-source software contribution, by making documentation into the gateway.

But even if you’re an expert, we want the Academy to be place to share knowledge, a place to get involved with new developments, and somewhere you can ask for help on your own projects.

The best way to get started is with our task list . Take a look, bookmark it, and see our Getting started guide for next steps.

Get in touch either through the task list, or through one of the following locations:

If you’d like to ask us questions outside of our public forums, feel free to email us at docsacademy@canonical.com.

In addition to the above, we have a weekly Documentation Office Hours starting at 16:00 UTC every Friday. Everyone is welcome, and links and comments can be found on the forum post.

Finally, subscribe to our Documentation event calendar. We’ll expand our Documentation Office Hours schedule and add other events throughout the year.

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

Some general tips:

  • use a spell checker

  • resist being overly formal

  • resist being overly verbose

  • verify links and examples

We (mostly) adhere to the Ubuntu 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

Diátaxis

Our navigational structure, style, and the content of our documentation follows the Diátaxis systematic framework for technical documentation authoring. This splits documentation pages into tutorials, how-to guides, reference material and explanatory text:

  • Tutorials are lessons that accomplish specific tasks through doing. They help with familiarity and place users in the safe hands of an instructor.

  • How-to guides are recipes, showing users how to achieve something, helping them get something done. A How-to has no obligation to teach.

  • Reference material is descriptive, providing facts about functionality that is isolated from what needs to be done.

  • Explanation is discussion, helping users gain a deeper or better understanding of Snap and Snapcraft, along with how and why they function as they do.

For further details on our Diátaxis strategy, see Diátaxis, a new foundation for Canonical documentation.

Improving our documentation and applying the principles of Diátaxis are on-going tasks. There’s a lot to do, and we don’t want to deter anyone from contributing to our docs. If you don’t know whether something should be a tutorial, how-to, reference doc or explanatory text, either ask on the forum or publish what you’re thinking. Changes are easy to make, and every contribution helps.

Markdown

Documentation is written in MyST Markdown.

Headings and titles

## Subheading within a document
### Subheading of a subheading

Headings and subheadings need to use sentence case, which means the first letter is typically the only one capitalised, unless the title includes names, product names or acronyms.

Lists

For a bullet list, use the following syntax:

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

And for a numbered list, precede each item with 1. (the numbering then becomes automatic, and it’s easier to insert new items):

1. This is the first item
1. This is the second
1. This is the third
   1. This is a sublist

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 the full stop to other items too.

Code blocks

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: bash, yaml, json, and no-highlight. The last is like a miscellaneous type. It is often used to display command output.

Also, a little contentiously as it goes against the style guide, we use a command line dollar prompt ($) to demarcate input and output in the same code block:

$ snap version
snap    2.36.1
snapd   2.36.1
series  16
ubuntu  18.04
kernel  4.15.0-39-generic

In sympathy with the command line, we replace $ with # when running commands from root.

Inline code

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

For instance, to create `$SNAP_DATA`:

Angle brackets and variable names

Angle brackets, <>, are typically used to show variables in example commands:

schema://<user name>:<password>@<address>:<port>/<name>

Example variable names are acceptable if you judge that the context makes it clear enough:

# set the working directory
WORKDIR /app
# copy the repository files to it
COPY . /app

In tutorials, provide the exact values that you want the user to use:

docker-compose run web django-admin startproject myapp .

Comments

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:

[quote]
:construction: **NOTE TO EDITORS** :construction:

This note is not visible in the dedicated documentation site.
[/quote]

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:

![description of image](url)