From c81132402859a0937fba2cb56729aa107d3f3527 Mon Sep 17 00:00:00 2001 From: Mary Camp Date: Thu, 10 Oct 2019 21:16:23 -0400 Subject: [PATCH] Upleveled Contribution guidelines, edited text. (#848) * Upleveled Contribution guidelines, edited text. Signed-off-by: MCamp859 * Simplify doc title and sub-bullets under Contrib. guidelines per standup, 10/10/19. Closed GH-828. Signed-off-by: Michael Vincerra --- source/collaboration/collaboration.rst | 74 +++++++++++++++++ .../collaboration/structure-formatting.rst | 0 .../collaboration/writing-guide.rst | 0 source/index.rst | 3 + .../reference/collaboration/collaboration.rst | 83 ------------------- source/reference/index.rst | 1 - 6 files changed, 77 insertions(+), 84 deletions(-) create mode 100644 source/collaboration/collaboration.rst rename source/{reference => }/collaboration/structure-formatting.rst (100%) rename source/{reference => }/collaboration/writing-guide.rst (100%) delete mode 100644 source/reference/collaboration/collaboration.rst diff --git a/source/collaboration/collaboration.rst b/source/collaboration/collaboration.rst new file mode 100644 index 00000000..b758a3f2 --- /dev/null +++ b/source/collaboration/collaboration.rst @@ -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 + Structure and formatting guide + +.. _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/ \ No newline at end of file diff --git a/source/reference/collaboration/structure-formatting.rst b/source/collaboration/structure-formatting.rst similarity index 100% rename from source/reference/collaboration/structure-formatting.rst rename to source/collaboration/structure-formatting.rst diff --git a/source/reference/collaboration/writing-guide.rst b/source/collaboration/writing-guide.rst similarity index 100% rename from source/reference/collaboration/writing-guide.rst rename to source/collaboration/writing-guide.rst diff --git a/source/index.rst b/source/index.rst index aa28a529..22b386d8 100644 --- a/source/index.rst +++ b/source/index.rst @@ -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 diff --git a/source/reference/collaboration/collaboration.rst b/source/reference/collaboration/collaboration.rst deleted file mode 100644 index 439f59bc..00000000 --- a/source/reference/collaboration/collaboration.rst +++ /dev/null @@ -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. - 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`_: - -#. 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/ \ No newline at end of file diff --git a/source/reference/index.rst b/source/reference/index.rst index 27e2088b..554a8c86 100644 --- a/source/reference/index.rst +++ b/source/reference/index.rst @@ -11,6 +11,5 @@ features. compatible-hardware bundles/bundles - collaboration/collaboration system-requirements image-types