Upleveled Contribution guidelines, edited text. (#848)

* Upleveled Contribution guidelines, edited text.

Signed-off-by: MCamp859 <maryx.camp@intel.com>

* Simplify doc title and sub-bullets under Contrib. guidelines per standup, 10/10/19.
Closed GH-828.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>
This commit is contained in:
Mary Camp
2019-10-10 18:16:23 -07:00
committed by michael vincerra
parent 1bc2804b1b
commit c811324028
6 changed files with 77 additions and 84 deletions
+74
View File
@@ -0,0 +1,74 @@
.. _collaboration:
Contribute
##########
There are multiple ways to help improve our documentation:
* `Contribute via GitHub`_: Submit pull requests in the GitHub\* documentation
repository.
* `Log an issue`_: Enter an issue in the documentation repository for
minor issues such as typos.
* `Make a suggestion`_: Send your documentation suggestion to the mailing list.
* Test documentation: Step through our guides and tutorials to verify the
instructions. `Log an issue`_ or `submit a pull request`_ with your findings.
All contributions must follow our `code of conduct`_.
Contribute via GitHub
*********************
Our documentation is hosted in GitHub and we follow the standard `GitHub flow`_.
Here are the basic steps for contributing:
#. 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.
Contribution guidelines
***********************
The |CL| documentation is written using reStructuredText. Use our guidelines
and best practices to write consistent, readable documentation.
.. toctree::
:maxdepth: 1
Writing guide <writing-guide>
Structure and formatting guide <structure-formatting>
.. _references:
References
**********
We use the following references for grammar, style, and formatting:
* `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
.. _Make a suggestion: https://lists.clearlinux.org/postorius/lists/dev.lists.clearlinux.org/
.. _GitHub flow: https://guides.github.com/introduction/flow/
.. _Log an issue: https://github.com/clearlinux/clear-linux-documentation/issues
.. _Contribute via GitHub: https://github.com/clearlinux/clear-linux-documentation
.. _submit a pull request: https://github.com/clearlinux/clear-linux-documentation
.. _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/
+3
View File
@@ -44,7 +44,9 @@ Our documentation is divided into the following sections:
The FAQ section provides answers to commonly asked questions about |CL|.
:ref:`collaboration`
This section describes how to contribute to |CL| documentation.
.. toctree::
:maxdepth: 2
@@ -56,3 +58,4 @@ Our documentation is divided into the following sections:
tutorials/index
reference/index
FAQ/index
collaboration/collaboration
@@ -1,83 +0,0 @@
.. _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/postorius/lists/dev.lists.clearlinux.org/
.. _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/
-1
View File
@@ -11,6 +11,5 @@ features.
compatible-hardware
bundles/bundles
collaboration/collaboration
system-requirements
image-types