mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-09-03 20:31:31 +00:00
83 lines
3.0 KiB
Plaintext
83 lines
3.0 KiB
Plaintext
.. _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/ |