Documentation guidelines

See a missing topic in the documentation? Find an existing document that could be improved? Help us out by contributing! If you haven’t contributed before, take a moment to review our Contribution guidelines.

Do you have questions about the documentation that were not answered by these guidelines? Send your question to the mailing list.

Contribution guidelines

The Clear Linux OS documentation is hosted in GitHub and is written using reStructuredText. Use our guidelines and best practices to write consistent, readable documentation.

• Writing guide: Describes the style we use to keep our documents clear and concise.
• Structure and formatting guide: Explains how we organize and format content, using reStructuredText and Sphinx.

How to contribute

There are multiple ways to contribute and help improve our documentation:

• Make a suggestion: Have a documentation suggestion but no time to write it yourself? Send your suggestion to the mailing list.
• Log an issue: If you find a problem in our documentation (such as typos or out-of-date information), log an issue in the documentation repository.
• Contribute directly via GitHub: Whether you’ve found a typo, have better instructions or examples, or have a new page to add, submit your improvement or addition as a pull request on the documentation repository.
• Test documentation: Step through our instructional guides and tutorials to verify the instructions. Log or correct any out-of-date information.

All contributions must follow our code of conduct.

Contribute via GitHub

Our documentation is hosted in GitHub and we follow the standard GitHub flow:

1. Clone the documentation repository.
2. Create your own fork of the repository.
3. Create a branch for your contribution.
4. Add your commits.
5. Open a pull request.
6. Discuss, review, and update your contributions.
7. Once the maintainer approves, your contribution is merged and published as part of the documentation.

References

We use the following references to guide the grammar, style, and formatting of our documentation:

• Microsoft Writing Style Guide
• Merriam-Webster Dictionary
• The Chicago Manual of Style (15th edition), The University of Chicago Press
• Microsoft Press Computer Dictionary, Microsoft Press
• Read Me First!, Oracle Technical Publications