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, fork 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 a combination of the MyST flavor of the Markdown and reStructuredText mark-up languages. MyST is preferred for new content. If you’re new to this, see our guides:

Semantic mark-up¶

We encourage (though not mandate) the use of semantic mark-up where possible. See Roles in Sphinx documentation for an overview of inline semantic roles available by default. The syntax is:

MyST	reStructuredText
{role}`term`	:role:`term`

The following roles are especially useful:

code: Source-code snippets.
command: Command-line interface (CLI) commands.
file: Names of files and directories (including path).
guilabel: Graphical user interface (GUI) elements: button, widgets, labels, …
kbd: Keyboard keys and shortcuts. Example:{kbd}`Shift+F1` (rendered as Shift+F1).
manpage: Link to an Ubuntu manual page. Example:{manpage}`man(1)` (rendered as a live link: man(1)).
pkg: Linux package name (this role is custom to this documentation project).

Command line and terminal output¶

Ubuntu Project documentation defaults to presenting command examples and terminal output in the following manner.

Command examples¶

To show an example of a command entered on the command line, use:

A regular literal block with language type none to prevent syntax highlighting.
Angled brackets (<>) to indicate a part to be substituted by the user.
Square brackets ([]) to indicate optional arguments.
Command split over multiple lines to avoid wrapping or the need to scroll.
Dollar ($) or hash (#) character to indicate normal user or superuser prompt respectively.

Example source for MyST:

```none
$ command --option=<mandatory_value> [optional_parameter] && \
  another-command --option --option2
```

Terminal output¶

When showing terminal output, use:

Separate blocks for the invocation and output.
Suitably shortened output to show only relevant parts.

Example source for MyST:

To enable the example service, run:

```none
$ examplectl start service
```

The output indicates that the example service is now active:

```none
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.

[...]
```

In case it is useful to show a command using a specific command-line prompt together with the output, use the terminal directive.

Example source for MyST:

Run the {command}`command` as the root user to achieve the folowing result:

```{terminal}
:user: root
:host: ubuntu
:dir: /tmp
:input: command --option

Lorem ipsum dolor sit amet, consectetur adipiscing elit
```

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.