Find issues to work on

We use GitHub issues to track documentation tasks. Start by checking out the issues list to see if there are any tasks you’d like to work on. We use labels to help filter the tasks that need to be done and to show whether they’re assigned to someone or not.

Get an issue assigned

When you find a task you want to work on, leave a comment on the issue saying you’d like to be assigned the task, with an estimated date for when you hope to complete it. One of the documentation maintainers will respond and assign that task to you.

Note

There is no time limit for completing a task, but if you need more time, need help, or won’t be able to complete the issue after all, make sure to comment on the issue to let us know. It’s quite normal for plans to change, and handing an issue back won’t prevent you from picking up more issues in the future!

Issues that have no work being done on them, with no updates from the author, will be considered stale after one month and will be unassigned to allow others a chance to pick them up.

Each issue can be worked on by a single person, and each person can work on one issue at a time. You can see which issues are unassigned by selecting “Assigned to nobody” from the “Assignee” drop-down menu (or use this link as a shortcut).

Issue labels

We use the following issue labels to help manage tasks. If you are looking for certain types of tasks, you can filter the issues list by label. The labels are grouped together into the following categories.

Note that we don’t use the help wanted or good first issue labels. All the issues we have can be considered as available for anyone who wants to work on them.

Coding level

These labels correspond to the different types of contributions that we accept according to the details in the Types of contributions page.

• code: technical

• code: coding

• code: low-code

• code: non-code

Content

These labels are used to mark out issues related to content. They will often also have a Diátaxis label to give more context.

• content: update

  Update specific instructions, commands, or version numbers.

• content: edit

  Edit existing content for consistency, accuracy, style, completeness and/or adherence to Diátaxis.

• content: new

  Add new documentation for a specific tool, feature, or function.

Diataxis

We use Diátaxis to organise our documentation. This label is used to suggest what documentation type the page in question belongs to. If you have a preference for writing how-to guides, for instance, you may want to filter by the how-to label.

If you want to suggest a missing guide, or have ideas about content you want to create, please make an issue first so we can discuss/agree upon the scope and how it will fit into the broader documentation.

• dia: tutorial

  Develop, write, or update a tutorial. Tutorials are often the hardest kind of documentation to create because they need good teaching skills before you even start writing.

• dia: how-to

  Create or update a how-to guide to achieve a specific goal. All our how-to guides follow a specific format - you can use our how-to template to help you (located in the contributing/doc-templates folder).

• dia: explanation

  Create or update an understanding-oriented explanation.

• dia: reference

  Create or update reference material.

ODA

The ODA label is used to show that this issue is also listed on the Canonical Open Documentation Academy.

Review

Review existing documentation. You may want to propose small updates to the original page after your review, or create a follow-up issue if you find substantial problems.

• review: wording

  Review the quality, clarity, and consistency of the wording. This may lead to follow-up edits.

• review: technical

  Review the technical accuracy, completeness, and up-to-dateness of the content. This may require follow-up updates.

Server labels

The set of Server: issues labels are for the maintainers of the repository to flag up possible problems with the listed issue or pull request.

Issues with the Server: WIP label are not intended to be worked on currently, either because they lack detail, need investigation, or need further instructions to be provided.

After you find an issue

After you have found an issue you want to work on, and have been assigned the issue, you will want to either use the GitHub web interface to create a quick pull request, or fetch the documentation to your own machine so you can build the documentation locally and work on your own local copy.