FAB-17967 Updates for new language contributors

Makes it easier for new contributors to the documentation to get started,
including international language translators.

Signed-off-by: Anthony O'Dowd <[email protected]>

Author: ODOWDAIBM

docs/README.md

@@ -1,116 +1,7 @@
 # Documentation README
 
-## Introduction
+If you'd like to contribute to the documentation, then read the following
+[instructions](./source/docs_guide.md) to get started.
 
-This document contains information on how the Fabric documentation is
-built and published as well as a few conventions one should be aware of
-before making changes to the doc.
-
-The crux of the documentation is written in
-[reStructuredText](http://docutils.sourceforge.net/rst.html) which is
-converted to HTML using [Sphinx](http://www.sphinx-doc.org/en/stable/).
-The HTML is then published on http://hyperledger-fabric.readthedocs.io
-which has a hook so that any new content that goes into `docs/source`
-on the main repository will trigger a new build and publication of the
-doc.
-
-## Conventions
-
-* Source files are in RST format and found in the `docs/source` directory.
-* The main entry point is index.rst, so to add something into the Table
-  of Contents you would simply modify that file in the same manner as
-  all of the other topics. It's very self-explanatory once you look at
-  it.
-* Relative links should be used whenever possible. The preferred
-  syntax for this is: :doc:\`anchor text <relativepath>\`
-  <br/>Do not put the .rst suffix at the end of the filepath.
-* For non RST files, such as text files, MD or YAML files, link to the
-  file on github, like this one for instance:
-  https://github.com/hyperledger/fabric/blob/master/docs/README.md
-
-Notes: The above means we have a dependency on the github mirror
-repository. Relative links are unfortunately not working on github
-when browsing through a RST file.
-
-## Setup
-
-Making any changes to the documentation will require you to test your
-changes by building the doc in a way similar to how it is done for
-production. There are two possible setups you can use to do so:
-setting up your own staging repo and publication website, or building
-the docs on your machine. The following sections cover both options:
-
-### Setting up your own staging repo and publication website
-
-You can easily build your own staging repo following these steps:
-
-1. Go to http://readthedocs.org and sign up for an account.
-2. Create a project.
-   Your username will preface the URL and you may want to append `-fabric` to ensure that you can distinguish between this and other docs that you need to create for other projects. So for example:
-   `yourgithubid-fabric.readthedocs.io/en/latest`.
-3. Click `Admin`, click `Integrations`, click `Add integration`, choose `GitHub incoming webhook`,
-   then click `Add integration`.
-4. Fork [Fabric on GitHub](https://github.com/hyperledger/fabric).
-5. From your fork, go to `Settings` in the upper right portion of the screen.
-6. Click `Webhooks`.
-7. Click `Add webhook`.
-8. Add the ReadTheDocs's URL into `Payload URL`.
-9. Choose `Let me select individual events`:`Pushes`、`Branch or tag creation`、`Branch or tag deletion`.
-10. Click `Add webhook`.
-
-Now anytime you modify or add documentation content to your fork, this
-URL will automatically get updated with your changes!
-
-### Building the docs on your machine
-
-Here are the quick steps to achieve this on a local machine without
-depending on ReadTheDocs, starting from the main fabric
-directory. Note: you may need to adjust depending on your OS.
-
-Prereqs:
- - [Python 3.7](https://wiki.python.org/moin/BeginnersGuide/Download)
- - [Pipenv](https://docs.pipenv.org/en/latest/#install-pipenv-today)
-
-```
-cd fabric/docs
-pipenv install
-pipenv shell
-make html
-```
-
-This will generate all the html files in `docs/build/html` which you can
-then start browsing locally using your browser. Every time you make a
-change to the documentation you will of course need to rerun `make
-html`.
-
-In addition, if you'd like, you may also run a local web server with the following commands (or equivalent depending on your OS):
-
-```
-sudo apt-get install apache2
-cd build/html
-sudo cp -r * /var/www/html/
-```
-
-You can then access the html files at `http://localhost/index.html`.
-
-## Updating Commands Reference topic
-
-Updating content in the [Commands Reference](https://hyperledger-fabric.readthedocs.io/en/latest/command_ref.html) topic requires additional steps. Because the information in the Commands Reference topic is generated content, you cannot simply update the associated markdown files.
-- Instead you need to update the `_preamble.md` or `_postscript.md` files under `src/github.com/hyperledger/fabric/docs/wrappers` for the command.
-- To update the command help text, you need to edit the associated `.go` file for the command that is located under `/fabric/internal/peer`.
-- Then, from the `fabric` folder, you need to run the command `make help-docs` which generates the updated markdown files under `docs/source/commands`. 
-
-Remember that when you push the changes to GitHub, you need to include the `_preamble.md`, `_postscript.md` or `_.go` file that was modified as well as the generated markdown file.
-
-### Adding a new CLI command
-
-To add a new CLI command, perform the following steps:
-
-- Create a new folder under `/fabric/internal/peer` for the new command and the associated help text. See `internal/peer/version` for a simple example to get started.
-- Add a section for your CLI command in `src/github.com/hyperledger/fabric/scripts/generateHelpDoc.sh`.
-- Create two new files under `/src/github.com/hyperledger/fabric/docs/wrappers` with the associated content:
-  - `<command>_preamble.md` (Command name and syntax)
-  - `<command>_postscript.md` (Example usage)
-- Run `make help-docs` to generate the markdown content and push all of the changed files to GitHub.  
-
-<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
+<!--- Licensed under Creative Commons Attribution 4.0 International License
+https://creativecommons.org/licenses/by/4.0/ -->

docs/source/CONTRIBUTING.rst

@@ -1,20 +1,14 @@
 Contributions Welcome!
 ======================
 
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-
-   style_guide
-
-We welcome contributions to Hyperledger in many forms, and
-there's always plenty to do!
+We welcome contributions to Hyperledger in many forms, and there's always plenty
+to do!
 
 First things first, please review the Hyperledger `Code of
 Conduct <https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct>`__
 before participating. It is important that we keep things civil.
 
-.. node:: If you want to contribute to this documentation, please check out the :doc:`style_guide`.
+.. note:: If you want to contribute to this documentation, please check out the :doc:`style_guide`.
 
 Ways to contribute
 ------------------
@@ -30,6 +24,28 @@ As a user:
   Contact the Epic assignee via the Jira work item or on
   `RocketChat <https://chat.hyperledger.org>`_.
 
+As a writer or information developer:
+
+- Update the documentation using your experience of Fabric and this
+  documentation to improve existing topics and create new ones.  A documentation
+  change is an easy way to get started as a contributor, makes it easier for
+  other users to understand and use Fabric, and grows your open source commit
+  history.
+
+- Participate in a language translation to keep the Fabric documentation current
+  in your chosen language.  The Fabric documentation is available in a number of
+  languages -- English, Chinese, Malayalam and Brazilian Portuguese -- so why
+  not join a team that keeps your favorite documentation up-to-date? You'll find
+  a friendly community of users, writers and developers to collaborate with.
+
+- Start a new language translation if the Fabric documentation isn't
+  available in your language.  The Chinese, Malayalam and Portuguese Brazilian
+  teams got started this way, and you can too!  It's more work, as you'll have
+  to form a community of writers, and organize contributions; but it's really
+  fulfilling to see the Fabric documentation available in your chosen language.
+
+Jump to `Contributing documentation`_ to get started on your journey.
+
 As a developer:
 
 - If you only have a little time, consider picking up a
@@ -73,6 +89,22 @@ already have one.
 6. Access `Jira issue management <https://jira.hyperledger.org>`__, or
    `RocketChat <https://chat.hyperledger.org/>`__.
 
+Contributing documentation
+--------------------------
+
+It's a good idea to make your first change a documentation change. It's quick
+and easy to do, checks that you have a correctly configured machine, (including
+the required pre-requisite software), and gets you familiar with the whole
+process.  Use the following sections to help you get started:
+
+.. toctree::
+   :maxdepth: 1
+
+   docs_guide
+   style_guide
+   international_languages
+
+
 Project Governance
 ------------------