Contribute to our documentation

We warmly welcome your engagement with the Landscape community and appreciate all contributions, suggestions, and feedback. There are many reasons why you should contribute to the Landscape documentation.

  • Improve your skills

    Contributing to the Landscape docs is a great way to improve your documentation and technical communication skills. You’ll get experience writing clear, concise documentation that’s helpful to the Landscape community, and you’ll have the opportunity to learn about writing documentation that focuses on user needs.

  • Give back to the community

    By contributing to the Landscape documentation, you foster a supportive community and can help other users learn about Landscape. Your contributions make a difference to other Landscape users!

  • Learn more about Landscape

    Contributing to the Landscape documentation can help you broaden your understanding of Landscape and its related technologies. Writing documentation often involves exploring new features and investigating potential problems or challenges users may face, which can help you learn more about how Landscape works and how users interact with it.

We believe that everyone has something valuable to contribute, no matter your level of experience, and we hope to make it as easy as possible to contribute. If you find any part of our process doesn’t work well for you, please let us know!

Prerequisites

There are some prerequisites to contributing to the Landscape documentation.

  • Code of Conduct: You will need to read and agree to the Ubuntu Code of Conduct. By participating, you implicitly agree to abide by the Code of Conduct.

  • GitHub account: You need a GitHub account to create issues, comment, reply, or submit contributions.

    You don’t need to know git before you start, and you definitely don’t need to work on the command line if you don’t want to. Many documentation tasks can be done using GitHub’s web interface. On the command line, we use the standard “fork and pull” process.

  • Licensing: The first time you contribute to a Canonical project, you will need to sign the Canonical License agreement (CLA). If you have already signed it, e.g. when contributing to another Canonical project, you do not need to sign it again.

    This license protects your copyright over your contributions, including the right to use them elsewhere, but grants us (Canonical) permission to use them in our project. You can read more about the CLA before you sign the CLA.

Landscape Docs overview and Diátaxis

This documentation is hosted in GitHub and rendered on Read the Docs. You need to create a GitHub account to contribute, but you don’t need a Read the Docs account.

Our navigational structure, style, and the content of our documentation follows the Diátaxis systematic framework for technical documentation authoring. This splits documentation pages into tutorials, how-to guides, reference material and explanatory text:

  • Tutorials are lessons that accomplish specific tasks through doing. They help with familiarity and place users in the safe hands of an instructor.

  • How-to guides are recipes, showing users how to achieve something, helping them get something done. A How-to guide has no obligation to teach.

  • Reference material is descriptive, providing facts about functionality that is isolated from what needs to be done.

  • Explanation is discussion, helping users gain a deeper or better understanding of Landscape, including how and why Landscape functions the way it does.

For further details on our Diátaxis strategy, see Diátaxis, a new foundation for Canonical documentation.

Improving our documentation and applying the principles of Diátaxis are on-going tasks. There’s a lot to do, and we don’t want to deter anyone from contributing to our docs. If you don’t know whether something should be a tutorial, how-to guide, reference doc or explanatory text, either ask on the forum or publish what you’re thinking. Changes are easy to make, and every contribution helps.

Ways to contribute

Most Landscape documentation contributions are made on GitHub. There are several ways you can contribute:

How to contribute

If you’re new to contributing with Git/GitHub or the command line, see the Getting Started guide from the Canonical Open Documentation Academy for an overview.

This section provides basic instructions of how to contribute to our documentation and build locally using GitHub and the command line.

Prerequisites

To build the documentation locally, you will first need to install some necessary dependencies on your system with the following commands:

sudo apt update
sudo apt install make python3 python3-venv python3-pip

Build, preview, and test the documentation

We use make to build, preview, and test the documentation. You can see all the options in the Makefile, but here’s the basic process:

Build

To build the docs:

make html

The first time you run this command, it’ll build everything. This includes installing all of the Python dependencies into the Python virtual environment. When you run it again, it’ll only update the changed files. This is usually fine, but sometimes causes issues if you’ve made a lot of structural changes to the documentation. You can also run a clean build, which deletes the existing output files and the Python environment, and then builds the full documentation again.

To run a clean build:

make clean html

Preview

After your build succeeds, preview it locally to see how the published documentation will look:

make run

This command builds the documentation and serves it at http://127.0.0.1:8000/. When you change a documentation file and save it, the documentation will be automatically rebuilt and refreshed in the browser.

Previewing the docs makes it easier to see how the finalized, published documentation will look. For most changes, you should preview your docs so you can make sure everything (especially the formatting) looks as you expected it to.

Test

You can do this before or after previewing the docs. We have two main tests which need to pass for our documentation:

make spelling
make linkcheck

These tests make sure everything is spelled correctly and that all links go to a valid URL. Note that these tests will also be run automatically on your pull request in GitHub.

Submit a pull request

Once you’ve finished creating and testing your changes, create a pull request against the Landscape documentation repository.

Your submitted issues and pull requests will be reviewed in due time. If you submit a PR, we have some automatic checks that will run against your PR to check for consistent style and language. However, don’t let this be a barrier to your contribution. You can still submit contributions to the best of your ability, and if something is inconsistent, we’ll help you fix it.