.. _collaboration:

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 |CL| documentation is hosted in GitHub and is written using
reStructuredText. Use our guidelines and best practices to write consistent,
readable documentation.

.. toctree::
   :maxdepth: 1

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

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`_:

#. Clone the `documentation repository`_.

#. Create your own fork of the repository.

#. Create a branch for your contribution.

#. Add your commits.

#. Open a pull request.

#. Discuss, review, and update your contributions.

#. Once the maintainer approves, your contribution is merged and published as
   part of the documentation.

.. _references:

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


.. _`code of conduct`: https://clearlinux.org/community/code-of-conduct
.. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev
.. _GitHub flow: https://guides.github.com/introduction/flow/
.. _documentation repository: https://github.com/clearlinux/clear-linux-documentation
.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
.. _Merriam-Webster Dictionary: https://www.merriam-webster.com/