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:
