Contribute to our documentation

Contributing to documentation is a great way to get started as a contributor to open-source projects, no matter your level of experience.

MicroCeph is growing rapidly, and we would love your help. We welcome, encourage and appreciate contributions from our user community in the form of suggestions, fixes and constructive feedback. Whether you are new to MicroCeph and want to highlight something you found confusing, or you’re an expert and want to create a how-to guide to help others, we will be happy to work with you to make our documentation better for everybody.

Raise an issue in our GitHub repository or talk to us on our Matrix channel.

We hope to make it as easy as possible to contribute. If you feel something is unclear, wrong, or broken, please don’t hesitate to leave a comment in the Matrix room.

MicroCeph documentation overview

The MicroCeph documentation is hosted in a GitHub repository and published on Read the Docs. You need to create a GitHub account to participate, but you do not need a Read the Docs account.

Contributing on GitHub

To create issues, comment, reply, or submit contributions, you need to set up a GitHub account and a Git environment. 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 model. Learn more about how to work with Git here.

For spelling and grammatical changes, which are quick and easy to submit, feel free to create a Pull Request (PR). For more substantial changes or suggestions, we recommend creating an issue first, so that we can discuss and agree on an approach before you spend time working on it.

Make sure to check the issues list before submitting a PR - if you start working on a task that is listed and already assigned to someone else, we won’t be able to accept your PR.

The CLA check

If it’s your first time contributing to a Canonical project, you will need to sign the Canonical Contributor Licence Agreement before your contribution can be considered for inclusion within our project. If you have already signed it, e.g. when contributing to another Canonical project, you do not need to sign it again. This licence protects your copyright over your contributions, including the right to use them elsewhere, but grants us (Canonical) permission to use them in our project. Our project repository will automatically check whether a contributor has signed the CLA when a contribution is made.

Diátaxis

Our documentation content, style and navigational structure follows the Diátaxis systematic framework for technical documentation authoring. This framework 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 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 MicroCeph, as well as how and why MicroCeph functions as it does.

To learn more about 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, 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.

Open Documentation Academy

MicroCeph is a proud member of the Canonical Open Documentation Academy (CODA), an initiative led by the documentation team at Canonical to provide help, advice, mentorship, and dozens of different tasks to get started on, within a friendly and encouraging environment.

A key aim of this initiative is to help lower the barrier into successful open-source software contribution, by making documentation into the gateway, and it’s a great way to make your first open source documentation contributions to MicroCeph.

But even if you’re an expert, we want the academy to be a place to share knowledge, a place to get involved with new developments, and somewhere you can ask for help on your own projects.

The best way to get started is with our task list . Take a look, bookmark it, and see our Getting started guide for next steps.

Stay in touch either through the task list, or through one of the following locations:

If you’d like to ask us questions outside of our public forums, feel free to email us at docsacademy@canonical.com.

In addition to the above, we have a weekly Community Hour starting at 16:00 UTC every Friday. Everyone is welcome, and links and comments can be found on the forum post.

Finally, subscribe to our Documentation event calendar. We’ll expand our Community Hour schedule and add other events throughout the year.

Agreements

Everyone involved with CODA needs to follow the words and spirit of the Ubuntu Code of Conduct v2.0. You must sign and agree to the Canonical CLA.

Identifying suitable task

The academy uses issue labels to give the contributor a glimpse into the task and what it requires, including the type of task, skills or level of expertise required, and even the size estimation for the task. You can find tasks of all sizes in the academy issues list.

From small tasks, such as replacing outdated terminology, checking for broken links, testing a tutorial or ensuring adherence to the Canonical documentation style guide; to medium-sized tasks like, converting documentation from one format to another, or migrating the contents of a blog post into the official documentation; to more ambitious tasks, such as adding a new How-to guide, restructuring a group of documents, or developing new tests and automations.

Completing and closing tasks

When a task has been completed to your satisfaction, we’ll ask the contributor whether they would prefer to merge their work into your project themselves, or leave this to the project.

Recognition

After successfully completing a task, we’ll give credit to the contributor and share their success in our forums, on the pages themselves, and in our news updates and release notes.

Guidance for writing

Consistency of writing style in documentation is vital for a good user experience. To accommodate our audience with a huge variation in experience, we:

  • write with our target audience in mind

  • 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

  • adhere to the style guide

Language

Canonical previously used British (GB) English, so you may notice that older documentation is in this format. However, we have recently switched to US English. It’s a good idea to set your spellchecker to en-US; which will pick up most of the inconsistencies. If it doesn’t, they will be picked up in review by the documentation team.

There are many small differences between UK and US English, but for the most part, it comes down to spelling. Some common differences are:

  • the ize suffix in preference to ise (e.g. capitalize rather than capitalise)

  • our instead of or (as in color and colour)

  • licence as both a verb and noun

  • catalog rather than catalogue

  • dates take the format 1 January 2013, 1-2 January 2025 and 1 January - 2 February 2025

We use an automated spelling checker that sometimes throws errors about terms we would like it to ignore:

  • If it complains about a file name or a command, enclose the word in backticks (`) to render it as inline code.

  • If the word is a valid acronym or a well-known technical term (that should not be rendered as code), add it to the spelling exception list, .custom_wordlist.txt (terms should be added in alphabetical order).

Both methods are valid, depending on whether you want the term to be rendered as normal font, or as inline code (monospaced).

Acronyms

Acronyms should always be capitalized.

They should always be expanded the first time they appear on a page, and then can be used as acronyms after that. E.g. OSD should be shown as Object Storage Daemon (OSD), and then can be referred to as OSD for the rest of the page.

Writing style

Try to be concise and to-the-point in your writing.

It’s alright to be a bit light-hearted and playful in your writing, but please keep it respectful, and don’t use emoji (they don’t render well in documentation, and may not be deemed professional).

It’s also good practice not to assume that your reader will have the same knowledge as you. If you’re covering a new topic (or something complicated) then try to briefly explain, or link to supporting explanations of, the things the typical reader may not know, but needs to (refer to the Diátaxis framework to help you decide what type of documentation you are writing and the level and type of information you need to include, e.g. a tutorial may require additional context but a how-to guide can skip some foundational knowledge - it is safer to assume some prior knowledge).

Thank you

We would like to thank you for spending your time to help make the MicroCeph documentation better. Every contribution, big or small, is important to us, and hopefully a step in the right direction.