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.

  • Connect with the Landscape community

    As a member of the Landscape community, you’re encouraged to collaborate with others and participate in discussions in the Discourse forum. Contributing to the documentation is a great way to connect with others in the community and learn from their experiences.

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:

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

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.