Discover open source through documentation
The Open Documentation Academy combines Canonical’s documentation team with documentation newcomers, experts, and those in-between, to help us all improve documentation practice and become better writers. Fill blanks in your resume and paint your GitHub activity tracker golden.
If you're a newcomer, we can provide help, advice, mentorship, and a hundred different tasks to get started on. If you're an expert, we want to create a place to share knowledge, a place to get involved with new developments, and somewhere you can ask for help on your own projects.
A key aim of this initiative is to help lower the barrier into successful open-source software contribution, by making documentation into the gateway.
The purpose of this repository is to list and track global documentation tasks. These are filed as issues in this repository. Tasks vary from broken formatting and missing documentation, to updates, re-structuring, and rewriting.
Issues are identified and shared by participating projects at Canonical who control whether an issue is merged into their documentation. An academy participant and a mentor work together to guide a contribution through to completion.
The first words of an issue's title will typically indicate the project it involved. These include the following:
- Canonical OpenStack: our enterprise cloud platform
- Juju: open source orchestration engine
- Canonical Kubernetes: the reference platform for Kubernetes on all major public clouds
- LXD: open source container and VM management at any scale
- Launchpad: software development lifecycle and collaboration platform
- MAAS: bare metal cloud with on-demand servers
- Our Sphinx and RST starter pack: our open source template for building modern documentation
- Snap and Snapcraft: Linux app packages and the build tools for desktop, cloud and IoT
- ubuntu-image: Tool for generating bootable Ubuntu images
This list will expand as more projects get involved. We're also happy to include projects outside of Canonical.
We use one or more of the following issue labels both for consistency and to indicate what might be expected from a task.
Revise a document to better conform to a Diátaxis type:
- Tutorial
- How-to
- Reference
- Explanation
This may require a document to be split, edited, or sometimes re-written.
Edit pre-existing documentation for consistency, accuracy, style and application.
Create or revise a document to better reflect an understanding-oriented explanation.
An ideal task to start with. Marking issues with this label is a widely adopted GitHub convention.
Another GitHub convention to indicate that a project welcomes community help with an issue.
Create or revise a document to better reflect a how-to guide to achieve a specific goal.
Adding new or missing documentation for a specific tool, feature, or function.
Tasks relating to the admin of the Open Documentation Academy (ODA) project.
Create or revise a document to better reflect a technical description to use as reference material.
Review pre-existing documentation for quality, accuracy and consistency. This work may require small updates to the original documentation and/or the creation of sub-tasks to address any detected and substantial shortcomings.
This is our estimation of effort and complexity. Size values range from 1 to 8, representing least effort to most effort respectively. These numbers follow the Fibonacci ### sequence sequence of 1, 2, 3, 5, 8, with size 8 likely to be a significant undertaking.
Develop, write, edit or update a tutorial. Tutorials are often the hardest kinds of documentation to write or update because they primarily require good teaching skills and perception, before you even start writing.
Update potentially outdated instructions, commands, or version numbers. These tasks might include release notes, version numbers, new command line arguments and features, and even complete overhauls when a major release occurs.
Our community forum is the hub for all things Open Documentation Academy. It includes our Getting started guide and links to our weekly Documentation office hours, alongside meeting notes, updates, external links and discussions.
https://discourse.ubuntu.com/c/open-documentation-academy
For more interactive chat, the documentation team can be found on Matrix.
https://matrix.to/#/#documentation:ubuntu.com
You can find us on Fosstodon, where we post frequent updates related to the Academy and our other documentation initiatives.
https://fosstodon.org/@CanonicalDocumentation
Subscribe to our Documentation event calendar. Not only does this include our Documentation office hours, it will also include any other discussion or training events we organise.