The Clear Linux* OS documentation contribution guidelines provide detailed information about the scope and purpose of the documentation, the accepted writing style, and the markup used.

The Clear Linux OS documentation is hosted in GitHub and welcomes community contributions. This guide provides rules to write clear, concise, and consistent content. Our documentation is written using ReStructuredText and we provide examples, templates, and best practices for that markup.

To contribute, follow the standard GitHub flow:

  1. Clone the Clear Linux 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 section.

The Clear Linux OS technical content is written in simple American English and our Language reference guide contains detailed information on that standard.

This guide includes the following sections:

Scope

The Clear Linux OS documentation is divided in five sections:

  • Get started: Information about installing Clear Linux.
  • Concepts: Detailed technical information about our features.
  • Guides: Step-by-step instructions to complete common tasks and configuration.
  • Tutorials: Step-by-step instructions to complete the installation and configuration of the tools needed for a specific use case.
  • Reference: Information providing additional context or details.

If you are unsure on which section to use for your contribution, send an email to our mailing list at: dev@lists.clearlinux.org Include the outline of the contribution you are planning and a brief description of its intended purpose and scope.

This style guide applies to the following technical content:

  • Commit messages
  • Technical presentations
  • All documents in ReStructuredText within and without the documentation repository
  • In-code comments
  • Release notes

We are always grateful to receive content contributions and are happy to help via our mailing list or our IRC channel, #clearlinux. If you have found a problem with one of our documents, please file a bug report.

Tone and audience

The tone of the Clear Linux OS documentation should be clear, concise, confident, and courteous. We write for our peers and want to be familiar. Use the second person, you or we, and active voice, we configure or you run, for example. Remain professional in your writing and carry an undertone of cordiality, respect, and cooperation.

Assume your audience has about the same level of technical understanding and expertise as you did when you first started collaborating. Do not talk down to our readers but do not assume they know everything about the subject. Offer brief explanations or summaries of “common knowledge” if a significant portion of readers might benefit.

All contributions must follow our code of conduct.

Methodology

This guide differs from other style guides and contains additional material not found in those sources.

To research a style question, look for the answer in this guide first. If the question is not answered here, send your question to the mailing list at: dev@lists.clearlinux.org.

If the question is answered in the existing style guide or dictionary, the solution is implemented and enforced as described.

References

In creating and refining the policies in this document, we consulted the following sources for guidance:

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

These sources do not always concur on questions of style and usage; nor do we always agree with these sources. In areas where there is disagreement, the decisions are explained in the respective section.

This guide takes precedence over all other style guides in all cases. In cases where the guide does not address the issue at hand, please report the issue to the mailing list using our bug report.

Use the Merriam-Webster’s Collegiate Dictionary to determine correct spelling, hyphenation, and usage.