How to contribute¶

This guide provides information necessary to contribute to this documentation. If you’re contributing for the first time, you might find the Canonical Open Documentation Academy has helpful resources to get you started.

Report an issue¶

To report a mistake on any page, or highlight some missing documentation, file an issue in our issues list on GitHub.

You can do this using the “Give feedback” button on any page, which will open a new issue.

Make sure to provide enough information in the issue for us to understand what is needed.

Edit documentation online¶

Each documentation page has a Contribute to this page link in the top-right corner (the pencil icon). Clicking this button opens the GitHub web editor where you can propose changes to that page. The first time you click this button, you will be prompted to create a fork of the documentation before you can start editing.

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

Contribute on GitHub¶

If you are familiar with a Git development workflow, checkout the Ubuntu Project docs repository and contribute your change as a pull request.

While this project is under construction, there will be a lot of movement in many different areas. To ensure that your efforts don’t get wasted due to overlaps, please either claim an open issue or, if there is no issue for what you want to work on, create a new issue first before working on your pull request.

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.

Build the documentation locally¶

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 Project docs repository. Visit Fork a repository for instructions.

Clone the repository to your machine:

git clone [email protected]:<your_user_name>/ubuntu-project-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 Project 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 your changes 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 install aspell.

Open Documentation Academy¶

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

The Open Documentation Academy (ODA) 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 is to lower the barrier of entry 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.