Merge pull request #1723 from Uma-95/1696-writing-guidelines

#1696-writing guidelines

Author: jaimergp

src/user/contributing.rst

@@ -20,29 +20,36 @@ Improve the documentation
 
 The ``conda-forge`` documentation is version-controlled in the
 `conda-forge.github.io repository
-<https://github.com/conda-forge/conda-forge.github.io>`_ on GitHub. The source
+<https://github.com/conda-forge/conda-forge.github.io>`__ on GitHub. The source
 text is stored in `the src/ subdirectory
-<https://github.com/conda-forge/conda-forge.github.io/tree/main/src>`_ of this repository
-(**not** the docs/ subdirectory) and
-is formatted using Python’s `reStructuredText
-<http://docutils.sourceforge.net/rst.html>`_ system.
+<https://github.com/conda-forge/conda-forge.github.io/tree/main/src>`__ of this repository and
+is formatted using Python's `reStructuredText
+<http://docutils.sourceforge.net/rst.html>`__ system.
+
+Editing the documentation directly through Github
+-------------------------------------------------
 
 You can propose quick edits directly through the GitHub website if you have
 a GitHub account — for instance, `this link
-<https://github.com/conda-forge/conda-forge.github.io/edit/main/src/user/contributing.rst>`_
+<https://github.com/conda-forge/conda-forge.github.io/edit/main/src/user/contributing.rst>`__
 will take you directly to a web-based editor for this very webpage. In
 general, the file corresponding to each page in the GitHub browser has a
 little pencil icon in its top-right corner that lets you open it up for editing.
 
-We are glad to know that you would like to contribute to the ``conda-forge`` documentation. If you are new to the conda-forge community, follow the steps below to make your first contribution:
+Editing the documentation locally
+---------------------------------
+
+We are glad to know that you would like to contribute to the ``conda-forge`` documentation. 
+If you are new to the conda-forge community, follow the steps below to make your first contribution:
 
-1. `Fork <https://help.github.com/articles/fork-a-repo/>`_ the
+1. `Fork <https://help.github.com/articles/fork-a-repo/>`__ the
    `conda-forge.github.io repository
-   <https://github.com/conda-forge/conda-forge.github.io>`_.
+   <https://github.com/conda-forge/conda-forge.github.io>`__.
 
 2. Clone this fork onto your local machine:
 
  - ``git clone https://github.com/<your-username>/conda-forge.github.io.git``
+ - ``cd conda-forge.github.io``
 
 3. Create a new branch deriving from ``main`` to do your work:
 
@@ -59,13 +66,30 @@ We are glad to know that you would like to contribute to the ``conda-forge`` doc
 
  - ``make html``
 
- You can check the changes locally by opening the html files in ``src/_build/html``.
+ You can check the changes locally by opening the html files in ``src/_build/html`` or running:
+ 
+ - ``python -m http.server --directory src/_build/html``
 
 6. Add and commit your changes:
 
  - ``git add .``
  - ``git commit -m "your commit message"``
 
-7. Submit a `pull request <https://help.github.com/articles/about-pull-requests/>`_ to the main repository proposing your changes.
+7. Submit a `pull request <https://help.github.com/articles/about-pull-requests/>`__ to the main repository proposing your changes.
 
 Happy contributing!
+
+Writing guidelines
+------------------
+   
+Some basic writing guidelines should be kept in mind before you start contributing:
+
+1. Identify your audience and understand their skill level.
+2. Match the technical language with the audience's skill level proficiency.
+3. Try to keep it simple. In case you have to use a lot of complicated terms, provide a glossary of key terms.
+4. Address the audience directly as the user(s).
+5. While mentioning an action, use the "command" form of the verb: "Choose an option from the menu and press Enter."   
+6. For references, provide links to related content. 
+7. Use headings and bullet points, which makes it easier to read.
+8. Avoid ambiguous titles. The title should include a clear description of the page's subject.
+9. Check your spellings and grammar.

src/user/introduction.rst

@@ -30,7 +30,6 @@ conda-forge is a community effort that tackles these issues:
  - Many packages are updated by multiple maintainers with an easy option to become a maintainer.
  - An active core developer team is trying to also maintain abandoned packages.
 
-
 How can I install packages from conda-forge?
 --------------------------------------------