How to contribute documentation¶

This guide provides information necessary to contribute to the Ubuntu for Developers documentation, especially if you’re contributing for the first time.

Reporting an issue¶

To report a mistake in or make request for the documentation, file an issue about it in our bug tracker on GitHub. to it.

Modifying documentation online¶

Each documentation page rendered on the web contains an Edit this page link in the top-right corner. Clicking this button leads you to the GitHub web editor where you can propose changes to the corresponding page.

Remember to first check the latest version of our documentation and make your proposal based on that revision.

Contributing on GitHub¶

To follow a Git development workflow, checkout the Ubuntu for Developers repository and contribute your changes as pull requests.

Directory structure¶

All the documentation files are located in the docs/ directory. The docs/ directory contains sub-directories corresponding to different Diátaxis sections:

explanation/
howto/
reference/
tutorial/

Add new articles in the appropriate directory. You can read about how Ubuntu implements Diátaxis for documentation.

Building the documentation¶

Follow these steps to build the documentation on your local machine.

Prerequisites¶

Git
The make tool

Note

The make command is compatible with Unix systems. On Windows, install Ubuntu with WSL.

Procedure¶

Fork the Ubuntu for Developers repository. Visit Fork a repository for instructions.

Clone the repository to your machine:

git clone [email protected]:<your_user_name>/ubuntu-for-developers-docs.git

Create a new branch:
```
git checkout -b <your_branch_name>
```
Change to the docs/ directory and make your contribution:
```
cd docs
```
Build a live preview of the documentation from within the docs/ directory:
```
make run
```
You can find all the HTML files in the .build/ directory.

make run uses the Sphinx autobuild module, so that any edits you make (and save) as you work are applied, and the built HTML files refresh immediately.
Review your contribution in a web browser by navigating to 127.0.0.1:8000.
Push your contribution to GitHub and create a pull request against the original repository.

Documentation format¶

The Ubuntu for Developers documentation is built with Sphinx using the MyST flavor of the Markdown mark-up language. If you’re new to Markdown or MyST, read our MyST style guide.

Testing the documentation¶

Test the documentation before submitting a pull request. Run the following commands from within the docs/ directory to test the documentation locally:

command	use
`make spelling`	Check for spelling errors; this command checks the HTML files in the `_build` directory. Fix any errors in the corresponding Markdown file
`make linkcheck`	Check for broken links
`make woke`	Check for non-inclusive language
`make pa11y`	Check for accessibility issues

Note

For the make spelling command to work, you must have the aspell spellchecker installed. You can install it with sudo apt-get install aspell.

Canonical Open Documentation Academy¶

If you’ve never contributed to an open source project before, the Canonical Open Documentation Academy (CODA) is a great way to begin.

The Canonical Open Documentation Academy (CODA) is an initiative led by the documentation team at Canonical to encourage open source contributions from the community, and to provide help, advice and mentorship within a friendly and welcoming environment.

A key aim of the initiative is to lower the barrier to successful open-source software contributions by making documentation into the gateway, and it’s a great way to make your first open source contributions to projects like ours. Contributors gain real experience, structured support and recognition, while we benefit from improvements to our documentation and community feedback.

The best way to get started is to take a look at our project-related documentation tasks and read our Getting started guide. Tasks typically include testing and fixing tutorials, updating outdated pages, restructuring large documents and anything else you may want to suggest. We’ll help you see those tasks through to completion.

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

Discussion forum on the Ubuntu Community Hub.
Matrix for interactive chat.
Fosstodon for the latest updates and events.

In addition to the above, we have a weekly Open Documentation Hour at 16:00 UTC each Friday. Everyone is welcome.