Jira documentation checklist

The snapd and Ubuntu Core engineering teams at Canonical use epics in Jira to manage tasks. The majority of these epics require documentation changes and additions.

When documentation is required, we add a documentation checklist to a Jira epic so that:

  • documentation requirements are understood by the team
  • documentation progress is tracked through to completion

An epic is not considered complete until all associated documentation checklist items are marked as Done.

Checklist formulation

For consistency across epics, and to ensure everyone understands the context and requirements for each documentation item, we have formulated a simple terminology for checklist items. This terminology borrows from both our Diátaxis documentation structure and our product architecture.

For example, if an epic requires changes to the snapd REST API, it would include the following documentation checklist item: DOCS: API

The following is a table of the terminology we’ve agreed to use for checklist items, alongside a description of when it’s needed and expectations for completion.

Each item in the checklist starts with DOCS: followed by one of the following:

Specific documentation targets

API Changes or additions to the snapd REST API
assertions Document a new Assertion, or update an existing assertion
component.yaml Changes or additions to the forthcoming component schema
gadget.yaml Changes or additions to the gadget.yaml snap schema
kernel.yaml Changes or additions to the kernel.yaml snap schema
snap.yaml Changes or additions to the snap.yaml schema

Example: DOCS: API

General documentation requirements

CLI Changes or additions to one of our command line tools, such as snap or snapctl
interface: Document a new interface, or update an existing interface
tutorial: General updates or additions to our Tutorial documentation
how-to: General updates or additions to our How-to documentation
reference: General updates that change our Reference documentation
explanation: General updates or additions to our Explanation documentation
other Used for other documentation requirements that don’t fall into any of the above categories. This requirement will need to be expanded upon within the Jira epic description

When the target document is ambiguous, the name of the target must be added manually.

Example: DOCS: interface: content

Example documentation checklist

The following is an example checklist for a Jira epic managing the development of components:

Jira documentation checklist