Contribute to our documentation
The Landscape documentation is published via the Discourse forum hosted at discourse.ubuntu.com. We appreciate any community contributions, suggestions and constructive feedback for the Landscape documentation. For the official docs, see the Landscape documentation.
New Discourse users
If you’re a new Discourse user, your capabilities will temporarily be limited. Discourse uses a trust system that grants experienced users more rights over time. New users start at Trust Level 0, but at Trust Level 1, you’ll be able to create new topics and reply to existing topics in Landscape’s Discourse forum.
Trust Level 1 is attained by:
- Entering at least 5 topics
- Reading at least 30 posts
- Spending a total of 10 minutes reading posts
First-time contributors
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.
How to contribute in Discourse
You can contribute to the Landscape documentation in Discourse by creating a new topic or replying to an existing one.
Create a new topic
There are several reasons why you may want to create a new topic. For example, you can:
- Write a new how-to guide
- Explain trouble-shooting steps you took to fix an error
- Suggest new guides that could be added to the documentation
- Provide detailed feedback for the documentation
- Ask a question to the community
To create a new topic in the Landscape Discourse forum, click New Topic, add a title, add your content, then click Create Topic. You can add an optional “Documentation” tag for topics related to the official Landscape documentation, although this step isn’t necessary.
Your topic may get replies, and you’re encouraged to participate with community members. Depending on the topic, we may publish it directly to the Landscape documentation.
Reply to an existing topic
You’re welcome to reply to topics posted by anyone in the community. We especially appreciate your replies on topics published in the Landscape documentation or topics requesting feedback.
To reply to an existing topic in the Discourse forum, click Reply (located below the topic contents).
Style and language
If your goal is to publish content in the official Landscape documentation, you’re particularly encouraged to read this section and the section on Diátaxis.
One of our biggest challenges is accommodating an audience with a huge variation in experience. Consequently, we try to:
- Write content in a tone that’s appropriate for the subject
- Write inclusively and assume very little prior knowledge of the reader
- Link or explain phrases, acronyms and concepts that may be unfamiliar, and if unsure, err on the side of caution
Some general tips:
- Use a spelling checker
- Resist being overly formal
- Resist being overly verbose
- Verify links and examples
We (mostly) adhere to the Ubuntu style guide. In particular:
- We use British English (en-GB), for example:
- the ise suffix in preference to ize (capitalise rather than capitalize)
- Our instead of or (as in colour and color)
- Catalogue rather than catalog
- Dates take the format 1 January 2023, 1-2 January 2023 and 1 January - 2 February 2023
Diátaxis
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.
Provide feedback
Your feedback is always appreciated. We have a topic in Discourse dedicated to providing general feedback here: Feedback on the Landscape documentation.
As always, you’re also welcome to create your own topic or reply to an existing topic in the forum.