[dpdk-dev] [PATCH 2/3] doc: added guidelines on dpdk documentation

[John McNamara <john.mcnamara@intel.com>]

Added guidelines on the purpose and structure of the DPDK
documentation, how to build it and guidelines for creating it.

Also added guidelines on how to format and submit a documentation patch.

Signed-off-by: John McNamara <john.mcnamara@intel.com>
---
 doc/guides/guidelines/documentation.rst | 1005 +++++++++++++++++++++++++++++++
 doc/guides/guidelines/index.rst         |    2 +
 2 files changed, 1007 insertions(+)
 create mode 100644 doc/guides/guidelines/documentation.rst

diff --git a/doc/guides/guidelines/documentation.rst b/doc/guides/guidelines/documentation.rst
new file mode 100644
index 0000000..d3e5905
--- /dev/null
+++ b/doc/guides/guidelines/documentation.rst
@@ -0,0 +1,1005 @@
+g.. doc_guidelines:
+
+DPDK Documentation Guidelines
+=============================
+
+This document outlines the guidelines for writing the DPDK Guides and API
+documentation in RST and Doxygen format.
+
+It also explains the structure of the DPDK documentation and shows how to
+build the Html and PDF versions of the documents.
+
+It also explains how to submit a patch to the documentation.
+
+
+Structure of the Documentation
+------------------------------
+
+The DPDK source code repository contains input files to build the API
+documentation and User Guides.
+
+The main directories that contain files related to documentation are shown
+below::
+
+   lib
+   |-- librte_acl
+   |-- librte_cfgfile
+   |-- librte_cmdline
+   |-- librte_compat
+   |-- librte_eal
+   |   |-- ...
+   ...
+   doc
+   |-- api
+   +-- guides
+       |-- freebsd_gsg
+       |-- linux_gsg
+       |-- prog_guide
+       |-- sample_app_ug
+       |-- guidelines
+       |-- testpmd_app_ug
+       |-- rel_notes
+       |-- nics
+       |-- xen
+       |-- ...
+
+
+The API documentation is built from `Doxygen
+<http://www.stack.nl/~dimitri/doxygen/>`_ comments in the header files. These
+files are mainly in the ``lib/lib_rte_*`` directories although some of the
+Poll Mode Drivers in ``drivers/net`` are also documented with Doxygen.
+
+The configuration files that are used to control the Doxygen output are in the
+``doc/api`` directory.
+
+The user guides such as *The Programmers Guide* and the *FreeBSD* and *Linux
+Getting Started* Guides are generated from RST markup text files using the
+`Sphinx <http://sphinx-doc.org/index.html>`_ Documentation Generator.
+
+These files are included in the ``doc/guides/`` directory. The output is
+controlled by the ``doc/guides/conf.py`` file.
+
+
+Role of the Documentation
+-------------------------
+
+The following items outline the roles of the different parts of the
+documentation and when they need to be updated or added to by the developer.
+
+* **Release Notes**
+
+  The Release Notes document which features have been added in the current and
+  previous releases of DPDK and highlight any known issues. The Releases Notes
+  also contain notifications of features that will change ABI compatibility in
+  the next major release.
+
+  In general developers do not have to update the Release Notes apart from
+  adding ABI announcements.
+
+* **API documentation**
+
+  The API documentation explains how to use the public DPDK functions. The
+  `API index page <http://dpdk.org/doc/api/>`_ shows the generated API
+  documentation as related groups of functions.
+
+  The API documentation should be updated via Doxygen comments when new
+  functions are added.
+
+* **Getting Started Guides**
+
+  The Getting Started Guides show how to install and configure DPDK and
+  how to run DPDK based applications on different OSes.
+
+  A Getting Started Guide should be added when DPDK is ported to a new OS. The
+  guide for the Skeleton Forwarding app is a good starting reference.
+
+* **The Programmers Guide**
+
+  The Programmers Guide explains how the API components of DPDK such as
+  the EAL, Memzone, Rings and the Hash Library work. It also explains how some
+  higher level functionality such as Packet Distributor, Packet Framework and
+  KNI work. It also shows the build system and explains how to add
+  applications.
+
+  The Programmers Guide should be expanded when new functionality is added to
+  DPDK.
+
+* **App Guides**
+
+  The app guides document the DPDK applications in the ``app`` directory such
+  as ``testpmd``.
+
+  The app guides should be updated if functionality is changed or added.
+
+* **Sample App Guides**
+
+  The sample app guides document the DPDK example applications in the examples
+  directory. Generally they demonstrate a major feature such as L2 or L3
+  Forwarding, Multi Process or Power Management. They explain the purpose of
+  the sample application, how to run it and step through some of the code to
+  explain the major functionality.
+
+  A new sample application should be accompanied by new sample app guide.
+
+* **Network Interface Controller Drivers**
+
+  The NIC Drivers document explains the features of the individual Poll Mode
+  Drivers, such as software requirements, configuration and initialization.
+
+  New documentation should be added for new Poll Mode Drivers.
+
+* **Guidelines**
+
+  The guideline documents record the DPDK guidelines on coding, design, ABI
+  usage and documentation.
+
+  These should be changed to clarify or improve guidelines.
+
+
+Building the Documentation
+--------------------------
+
+Dependencies
+~~~~~~~~~~~~
+
+
+The following dependencies must be installed to build the documentation:
+
+* Doxygen.
+
+* Sphinx.
+
+* TexLive.
+
+* Inkscape.
+
+`Doxygen`_ generates documentation from commented source code. It can be
+installed as follows:
+
+.. code-block:: console
+
+   # Ubuntu/Debian.
+   sudo apt-get -y install doxygen
+
+   # Red Hat/Fedora.
+   sudo yum     -y install doxygen
+
+`Sphinx`_ is a Python documentation tool for converting RST files to Html or
+to PDF (via LaTeX). It can be installed as follows:
+
+.. code-block:: console
+
+   # Ubuntu/Debian.
+   sudo apt-get -y install python-sphinx
+
+   # Red Hat/Fedora.
+   sudo yum     -y install python-sphinx
+
+   # Or, on any system with Python installed.
+   sudo easy_install -U sphinx
+
+For further information on getting started with Sphinx see the `Sphinx
+Tutorial <http://sphinx-doc.org/tutorial.html>`_.
+
+.. Note::
+
+   To get full support for Figure and Table numbering it is best to install
+   Sphinx 1.3.1 or later.
+
+
+`Inkscape`_ is a vector based graphics program which is used to create SVG
+images and also to convert SVG images to PDF images. It can be installed as
+follows:
+
+.. code-block:: console
+
+   # Ubuntu/Debian.
+   sudo apt-get -y install inkscape
+
+   # Red Hat/Fedora.
+   sudo yum     -y install inkscape
+
+`TexLive <http://www.tug.org/texlive/>`_ is an installation package for
+Tex/LaTeX. It is used to generate the PDF versions of the
+documentation. Installation of all of the TeX components required by Sphinx
+can be tricky. If possible it is best to install TexLive Full to ensure that
+you have all the requirements. It can be installed as follows:
+
+.. code-block:: console
+
+   # Ubuntu/Debian.
+
+   sudo apt-get -y install texlive-full
+
+   # Red Hat/Fedora, selective install.
+   sudo yum -y install texlive
+   sudo yum -y install texlive-latex
+   sudo yum -y install texlive-collection-latex
+   sudo yum -y install texlive-collection-latexrecommended
+   sudo yum -y install texlive-collection-latexextra
+   sudo yum -y install texlive-dejavu
+
+
+Build commands
+~~~~~~~~~~~~~~
+
+The documentation is built using the standard DPDK build system. Some examples
+are shown below:
+
+* Generate all the documentation targets::
+
+     make doc
+
+* Generate the Doxygen API documentation in Html::
+
+     make doc-api-html
+
+* Generate the guides documentation in Html::
+
+     make doc-guides-html
+
+* Generate the guides documentation in Pdf::
+
+     make doc-guides-pdf
+
+The output of these commands is generated in the ``build`` directory::
+
+   build/doc
+         |-- html
+         |   |-- api
+         |   +-- guides
+         |
+         +-- pdf
+             +-- guides
+
+
+.. Note::
+
+   Make sure to fix any Sphinx or Doxygen warnings when adding or updating
+   documentation.
+
+The documentation output files can be removed as follows::
+
+   make doc-clean
+
+
+Document Guidelines
+-------------------
+
+Here are some guidelines in relation to the style of the documentation:
+
+* Document the obvious as well as the obscure since it won't always be obvious
+  to the reader. For example an instruction like "Set up 64 2MB Hugepages" is
+  better when followed by a sample commandline or a link to the appropriate
+  section of the documentation.
+
+* Use American English spellings throughout. This can be checked using the
+  ``aspell`` utility::
+
+       aspell --lang=en_US --check doc/guides/sample_app_ug/mydoc.rst
+
+
+RST Guidelines
+--------------
+
+The RST (reStructuredText) format is a plain text markup format that can be
+converted to Html, PDF or other formats. It is most closely associated with
+Python but it can be used to document any language. It is used in DPDK to
+document everything apart from the API.
+
+The Sphinx documentation contains a very useful `RST Primer
+<http://sphinx-doc.org/rest.html#rst-primer>`_ which is a good place to learn
+the minimal set of syntax required to format a document.
+
+The official `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
+website contains the specification for the RST format and also examples of how
+to use it. However, for most developers the RST Primer above is a better
+resource.
+
+The most common guidelines for writing RST text are detailed in the
+`Documenting Python <https://docs.python.org/devguide/documenting.html>`_
+guidelines. The additional guidelines below reiterate or expand upon those
+guidelines.
+
+
+Readability
+~~~~~~~~~~~
+
+The main RST guideline is that the RST text should be readable in text format.
+
+Even though RST is a markup format and the text will most often be read when
+rendered to Html or PDF it is important to maintain readability of the raw
+text. This makes is easier for developers to read in an editor or in a
+terminal.
+
+
+Line Length
+~~~~~~~~~~~
+
+The existing documentation contains different styles for long lines and
+paragraphs. The following are recommendations for new text in order of
+preference:
+
+* Wrap lines at 80 characters. This is the Python RST recommendation and adds
+  to readability of the raw text.
+
+* Use one sentence per line in a paragraph, i.e., put a newline character
+  after each period/full stop.
+
+* Use one line per paragraph.
+
+
+Whitespace
+~~~~~~~~~~
+
+* Standard RST indentation is 3 spaces. Code can be indented 4 spaces,
+  especially if it is copied from source files.
+
+* No tabs. Convert tabs in embedded code to 4 or 8 spaces.
+
+* No trailing whitespace.
+
+* The most common existing style in the documentation is to have only 1 space
+  after a period/full stop.
+
+* Add 2 blank lines before each section header.
+
+* Add 1 blank line after each section header.
+
+* Add 1 blank line between each line of a list.
+
+
+Section Headers
+~~~~~~~~~~~~~~~
+
+* Section headers should use the use the following underline formats::
+
+   Level 1 Heading
+   ===============
+
+
+   Level 2 Heading
+   ---------------
+
+
+   Level 3 Heading
+   ~~~~~~~~~~~~~~~
+
+
+   Level 4 Heading
+   ^^^^^^^^^^^^^^^
+
+
+* Level 4 headings should be used sparingly.
+
+* The underlines should match the length of the text.
+
+* In general, the heading should be less than 80 characters.
+
+* As noted above:
+
+   * Add 2 blank lines before each section header.
+
+   * Add 1 blank line after each section header.
+
+
+Lists
+~~~~~
+
+* Bullet lists should be formatted with a leading ``*`` as follows::
+
+     * Item one.
+
+     * Item two is a longer line that is wrapped at 80 characters and then
+       indented to match the start of the first line.
+
+     * One space character between the bullet and the text is preferred.
+
+* Numbered lists can be formatted with a leading number but the preference is
+  to use ``#.`` which will give automatic numbering. This is more convenient
+  when adding or removing items::
+
+     #. Item one.
+
+     #. Item two is a longer line that is wrapped at 80 characters and then
+        indented to match the start of the e first line.
+
+* Definition lists can be written with or without a bullet::
+
+     * Item one.
+
+       Some text about item one.
+
+     * Item two.
+
+       Some text about item two.
+
+* All lists, and sub-lists, must be separated from the preceding text by a
+  blank line. This is a syntax requirement.
+
+* All list items should be separated by a blank line for readability.
+
+
+Code and Literal block sections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Inline text that is required to be rendered with a fixed width font should
+  be enclosed in backquotes like this: \`\`text\`\`, so that it appears like
+  this: ``text``.
+
+* Fixed width, literal blocks of texts should be indented at least 3 spaces
+  and prefixed with ``::`` like this::
+
+     Here is some fixed width text::
+
+        0x0001 0x0001 0x00FF 0x00FF
+
+* It is also possible to specify an encoding for a literal block using the
+  ``.. code-block::`` directive so that syntax highlighting can be
+  applied. Examples of supported highlighting are::
+
+     .. code-block:: console
+     .. code-block:: c
+     .. code-block:: python
+     .. code-block:: diff
+     .. code-block:: none
+
+  That can be applied as follows::
+
+      .. code-block:: c
+
+         #include<stdio.h>
+
+         int main() {
+
+            printf("Hello World\n");
+
+            return 0;
+         }
+
+  Which would be rendered as:
+
+  .. code-block:: c
+
+      #include<stdio.h>
+
+      int main() {
+
+         printf("Hello World\n");
+
+         return 0;
+      }
+
+
+* The default encoding for a literal block using the simplified ``::``
+  directive is ``none``.
+
+* Avoid lines longer than 80 character in literal blocks since they can exceed
+  the page width when converted to PDF documentation. If possible try to wrap
+  the text at sensible locations. For example a long command line could be
+  documented like this and still work if copied directly from the docs::
+
+     build/app/testpmd -c7 -n3 --vdev=eth_pcap0,iface=eth0     \
+                               --vdev=eth_pcap1,iface=eth1     \
+                               -- -i --nb-cores=2 --nb-ports=2 \
+                                  --total-num-mbufs=2048
+
+
+Images
+~~~~~~
+
+* All images should be in SVG scalar graphics format. They should be true SVG
+  XML files and should not include binary formats embedded in a SVG wrapper.
+
+* The DPDK documentation contains some legacy images in PNG format. These will
+  be converted to SVG in time.
+
+* `Inkscape <inkscape.org>`_ is the recommended graphics editor for creating
+  the images. Use some of the older images in ``doc/guides/prog_guide/img/``
+  as a template, for example ``mbuf1.svg`` or ``ring-enqueue.svg``.
+
+* The SVG images should include a copyright notice, as an XML comment.
+
+* Images in the documentation should be formatted as follows:
+
+   * The image should be preceded by a label in the format
+     ``.. _figure_XXXX:`` with a leading underscore and where ``XXXX`` is a
+     unique descriptive name.
+
+   * Images should be included using the ``.. figure::`` directive and the
+     file type should be set to ``*`` (not ``.svg``). This allows the format
+     of the image to be changed if required.
+
+   * Images must have a caption as part of the ``.. figure::`` directive.
+
+* Here is an example of the previous three guidelines::
+
+     .. _figure_mempool:
+
+     .. figure:: img/mempool.*
+
+        A mempool in memory with its associated ring.
+
+.. _mock_label:
+
+* Images can then be linked to using the ``:numref:`` directive::
+
+     The mempool layout is shown in :numref:`figure_mempool`.
+
+  This would be rendered as: *The mempool layout is shown in* :ref:`Fig 6.3
+  <mock_label>`.
+
+  **Note**: The ``:numref:`` directive requires Sphinx 1.3.1 or later. With
+  earlier versions it will still be rendered as a link but won't have an
+  automatically generated number.
+
+* The caption of the image can be generated, with a link, using the ``:ref:``
+  directive::
+
+     :ref:`figure_mempool`
+
+  This would be rendered as: *A mempool in memory with its associated ring.*
+
+Tables
+~~~~~~
+
+* RST tables should be used sparingly. They are hard to format and to edit,
+  they are often rendered incorrectly in PDF format, and the same information
+  can usually be shown just as clearly with a list.
+
+* Tables in the documentation should be formatted as follows:
+
+   * The table should be preceded by a label in the format
+     ``.. _table_XXXX:`` with a leading underscore and where ``XXXX`` is a
+     unique descriptive name.
+
+   * Tables should be included using the ``.. table::`` directive and must
+     have a caption.
+
+* Here is an example of the previous two guidelines::
+
+     .. _table_qos_pipes:
+
+     .. table:: Sample configuration for QOS pipes.
+
+        +----------+----------+----------+
+        | Header 1 | Header 2 | Header 3 |
+        |          |          |          |
+        +==========+==========+==========+
+        | Text     | Text     | Text     |
+        +----------+----------+----------+
+        | ...      | ...      | ...      |
+        +----------+----------+----------+
+
+* Tables can be linked to using the ``:numref:`` and ``:ref:`` directives, as
+  shown in the previous section for images. For example::
+
+     The QOS configuration is shown in :numref:`table_qos_pipes`.
+
+* Tables should not include merged cells since they are not supported by the
+  PDF renderer.
+
+
+.. _links:
+
+Hyperlinks
+~~~~~~~~~~
+
+* Links to external websites can be plain URLs. The following is rendered as
+  http://dpdk.org::
+
+     http://dpdk.org
+
+* They can contain alternative text. The following is rendered as
+  `Check out DPDK <http://dpdk.org>`_::
+
+     `Check out DPDK <http://dpdk.org>`_
+
+* An internal link can be generated by placing labels in the document with the
+  format ``.. _label_name``.
+
+* The following links to the top of this section: :ref:`links`::
+
+     .. _links:
+
+     Hyperlinks
+     ~~~~~~~~~~
+
+     * The following links to the top of this section: :ref:`links`:
+
+.. Note::
+
+   The label must have a leading underscore but the reference to it must omit
+   it. This is a frequent cause of errors and warnings.
+
+* The use of a label is preferred since it works across files and will still
+  work if the header text changes.
+
+
+.. _doxygen_guidelines:
+
+Doxygen Guidelines
+------------------
+
+The DPDK API is documented using Doxygen comment annotations in the header
+files. Doxygen is a very powerful tool, it is extremely configurable and with
+a little effort can be used to create expressive documents. See the `Doxygen
+website <http://www.stack.nl/~dimitri/doxygen/>`_ for full details on how to
+use it.
+
+The following are some guidelines for use of Doxygen in the DPDK API
+documentation:
+
+* New libraries that are documented with Doxygen should be added to the
+  Doxygen configuration file: ``doc/api/doxy-api.conf``. It is only required
+  to add the directory that contains the files. It isn't necessary to
+  explicitly name each file since the configuration matches all ``rte_*.h``
+  files in the directory.
+
+* Use proper capitalization and punctuation in the Doxygen comments since they
+  will become sentences in the documentation. This in particular applies to
+  single line comments, which is the case the is most often forgotten.
+
+* Use ``@`` style Doxygen commands instead of ``\`` style commands.
+
+* Add a general description of each library at the head of the main header
+  files:
+
+  .. code-block:: c
+
+      /**
+       * @file
+       * RTE Mempool.
+       *
+       * A memory pool is an allocator of fixed-size object. It is
+       * identified by its name, and uses a ring to store free objects.
+       * ...
+       */
+
+* Document the purpose of a function, the parameters used and the return
+  value:
+
+  .. code-block:: c
+
+     /**
+      * Attach a new Ethernet device specified by arguments.
+      *
+      * @param devargs
+      *  A pointer to a strings array describing the new device
+      *  to be attached. The strings should be a pci address like
+      *  `0000:01:00.0` or **virtual** device name like `eth_pcap0`.
+      * @param port_id
+      *  A pointer to a port identifier actually attached.
+      *
+      * @return
+      *  0 on success and port_id is filled, negative on error.
+      */
+     int rte_eth_dev_attach(const char *devargs, uint8_t *port_id);
+
+* Doxygen supports Markdown style syntax such as bold, italics, fixed width
+  text and lists. For example the second line in the ``devargs`` parameter in
+  the previous example will be rendered as:
+
+     The strings should be a pci address like ``0000:01:00.0`` or **virtual**
+     device name like ``eth_pcap0``.
+
+* Use ``-`` instead of ``*`` for lists within the Doxygen comment since the
+  latter can get confused with the comment delimiter.
+
+* Add an empty line between the function description, the ``@params`` and
+  ``@return`` for readability.
+
+* Place the ``@params`` description on separate line and indent it by 2
+  spaces. (It would be better to use no indentation since this is more common
+  and also because checkpatch complains about leading whitespace in
+  comments. However this is the convention used in the existing DPDK code.)
+
+* Documented functions can be linked to simply by adding ``()`` to the
+  function name:
+
+  .. code-block:: c
+
+      /**
+       * The functions exported by the application Ethernet API to setup
+       * a device designated by its port identifier must be invoked in
+       * the following order:
+       *     - rte_eth_dev_configure()
+       *     - rte_eth_tx_queue_setup()
+       *     - rte_eth_rx_queue_setup()
+       *     - rte_eth_dev_start()
+       */
+
+  In the API documentation the functions will be rendered as links, see the
+  `online section of the rte_ethdev.h docs
+  <http://dpdk.org/doc/api/rte__ethdev_8h.html>`_ that contains the above
+  text.
+
+* The ``@see`` keyword can be used to create a *see also* link to another file
+  or library. This directive should be placed on one line at the bottom of the
+  documentation section.
+
+  .. code-block:: c
+
+     /**
+      * ...
+      *
+      * Some text that references mempools.
+      *
+      * @see eal_memzone.c
+      */
+
+* Doxygen supports two types of comments for documenting variables, constants
+  and members: prefix and postfix:
+
+  .. code-block:: c
+
+     /** This is a prefix comment. */
+     #define RTE_FOO_ERROR  0x023.
+
+     #define RTE_BAR_ERROR  0x024. /**< This is a postfix comment. */
+
+* Postfix comments are preferred for struct members and constants if they can
+  be documented in the same way:
+
+  .. code-block:: c
+
+     struct rte_eth_stats {
+         uint64_t ipackets; /**< Total number of received packets. */
+         uint64_t opackets; /**< Total number of transmitted packets.*/
+         uint64_t ibytes;   /**< Total number of received bytes. */
+         uint64_t obytes;   /**< Total number of transmitted bytes. */
+         uint64_t imissed;  /**< Total of RX missed packets. */
+         uint64_t ibadcrc;  /**< Total of RX packets with CRC error. */
+         uint64_t ibadlen;  /**< Total of RX packets with bad length. */
+     }
+
+  Note: postfix comments should be aligned with spaces not tabs in accordance
+  with the :ref:`coding_style`.
+
+* If a single comment type can't be used, due to line length limitations then
+  prefix comments should be preferred. For example this section of the code
+  contains prefix comments, postfix comments on the same line and postfix
+  comments on a separate line:
+
+  .. code-block:: c
+
+     /** Number of elements in the elt_pa array. */
+     uint32_t    pg_num __rte_cache_aligned;
+     uint32_t    pg_shift;     /**< LOG2 of the physical pages. */
+     uintptr_t   pg_mask;      /**< Physical page mask value. */
+     uintptr_t   elt_va_start;
+     /**< Virtual address of the first mempool object. */
+     uintptr_t   elt_va_end;
+     /**< Virtual address of the <size + 1> mempool object. */
+     phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT];
+     /**< Array of physical page addresses for the mempool buffer. */
+
+  This doesn't have an effect on the rendered documentation but it is
+  confusing for the developer reading the code. It this case it would be
+  clearer to use prefix comments throughout:
+
+  .. code-block:: c
+
+     /** Number of elements in the elt_pa array. */
+     uint32_t    pg_num __rte_cache_aligned;
+     /** LOG2 of the physical pages. */
+     uint32_t    pg_shift;
+     /** Physical page mask value. */
+     uintptr_t   pg_mask;
+     /** Virtual address of the first mempool object. */
+     uintptr_t   elt_va_start;
+     /** Virtual address of the <size + 1> mempool object. */
+     uintptr_t   elt_va_end;
+     /** Array of physical page addresses for the mempool buffer. */
+     phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT];
+
+* Check for Doxygen warnings in new code by checking the API documentation
+  build::
+
+     make doc-api-html | grep "warning:"
+
+* Read the rendered section of the documentation that you have added for
+  correctness, clarity and consistency with the surrounding text.
+
+
+Patching the Documentation
+--------------------------
+
+One of the easiest ways to contribute to DPDK is to submit a patch to the
+documentation.
+
+Over time the documentation may contain information that is slightly out of
+date or that could be improved upon. Newcomers to the DPDK project often
+notice these issues as they work through the examples and how-to guides.
+
+Rather than emailing the development list, or even ignoring the issue, it is
+just as easy to submit a patch to fix it. The following instructions explain
+how to do that and since they are meant to encourage contributions they assume
+no development experience or prior exposure to the DPDK workflow.
+
+#. Install the documentation dependencies as shown above. As a minimum you
+   should install Sphinx::
+
+      # Ubuntu/Debian.
+      sudo apt-get -y install python-sphinx
+
+      # Red Hat/Fedora.
+      sudo yum     -y install python-sphinx
+
+   If you are going to patch the API docs you will need Doxygen. You can omit
+   TexLive and Inkscape for now.
+
+#. Install ``git`` as follows::
+
+      # Ubuntu/Debian.
+      sudo apt-get -y install git
+
+      # Red Hat/Fedora.
+      sudo yum     -y install git
+
+   If you have any problems, refer to the official `Git installation guide
+   <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_.
+
+#. Configure your ``.gitconfig`` file with your name and email address::
+
+      git config --global user.name "J. Smith"
+      git config --global user.email jsmith@example.com
+
+   If you wish you can also configure the default editor that is used to write
+   commit messages::
+
+      git config --global core.editor vi
+
+   See the `Git getting started guide
+   <https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup>`_ if
+   you have any issues.
+
+#. Clone the DPDK repository (this can take a minute or two)::
+
+      git clone http://dpdk.org/git/dpdk
+
+#. Change into the new ``dpdk`` directory and test if you have the required
+   dependencies to build the docs::
+
+      cd dpdk
+      make doc-guides-html
+
+   If you get warnings about missing utilities go back and work through
+   installing the dependencies again.
+
+   If you installed some of the other dependencies you can try the following,
+   but they aren't required::
+
+      # If you installed Doxygen:
+      make doc-api-html
+
+      # If you installed Inkscape and TexLive as well:
+      make doc
+
+   .. Note::
+
+      You can ignore a warning about upgrading Sphinx, that is optional. If
+      you are building the documentation on Mac OS you can ignore a warning
+      from ``sed``.
+
+#. Using your preferred editor make the changes to the file you want to fix or
+   improve. For example::
+
+      vi doc/guides/linux_gsg/quick_start.rst
+
+#. Once you have make the modifications you should see a change in the ``git
+   status``::
+
+      git status
+
+      On branch master
+      Your branch is up-to-date with 'origin/master'.
+      Changes not staged for commit:
+        (use "git add <file>..." to update what will be committed)
+        (use "git checkout -- <file>..." to discard changes)
+
+        modified:   doc/guides/linux_gsg/quick_start.rst
+
+
+#. You will be able to review your changes using ``git diff``:
+
+   .. code-block:: diff
+
+      git diff
+
+      diff --git a/quick_start.rst b/quick_start.rst
+      index b07fc87..7b49e1c 100644
+      --- a/doc/guides/linux_gsg/quick_start.rst
+      +++ b/doc/guides/linux_gsg/quick_start.rst
+      @@ -256,7 +256,7 @@ The following selection demonstrates the launch
+
+           Enter hex bitmask of cores to execute test app on
+           Example: to execute app on cores 0 to 7, enter 0xff
+      -    bitmaks: 0x01
+      +    bitmask: 0x01
+           Launching app
+           EAL: coremask set to 1
+           EAL: Detected lcore 0 on socket 0
+
+   Two other diff options that are useful when dealing with changes to
+   documentation are word and character diffs::
+
+      # View differences by word instead of lines:
+      git diff --color-words
+
+      # View differences by character:
+      git diff --color-words=.
+
+
+#. Rebuild the docs and fix any new warnings::
+
+      make doc-guides-html
+
+#. Open the output Html document and review your changes in the context of the
+   surrounding text. Use a Web browser like the following::
+
+      firefox build/doc/html/guides/linux_gsg/quick_start.html &
+
+#. If everything is okay you can commit your changes to your local repository
+   and generate a patch. The first step is to add the file(s) that you
+   modified::
+
+      git add doc/guides/linux_gsg/quick_start.rst
+
+#. Now commit the changes to the local repository. You must "sign" the commit
+   by using ``-s``. This will insert the name and email address that you
+   configured in your ``.gitconfig`` above::
+
+      git commit -s
+
+   This will drop you into the default, or configured, editor and you can
+   insert a message like the following::
+
+      doc: fix minor typo in linux getting started guide
+
+      Fixed a minor typo in the Linux Getting Started Guide.
+
+      Signed-off-by: J. Smith <jsmith@example.com>
+
+   The first line will be used as a subject line for an email so it should:
+
+   * start with ``doc:``
+   * be less than 50 characters
+   * be lowercase only
+   * and not end with a period/full stop
+
+   The body of the text should:
+
+   * describe the change
+   * be wrapped at 72 characters
+   * have proper punctuation and capitalization
+
+   The body of the message should generally be longer than the example above
+   and should explain the purpose of the change.
+
+#. You can now create and email a patch. This can be done in one step from git
+   but for beginners it is best done in two steps so that you can review the
+   patch. First generate the patch::
+
+      git format-patch -1
+
+   This will generate a patch like the following::
+
+      0001-doc-fix-minor-typo-in-linux-getting-started-guide.patch
+
+   If you have a large patch or set of patches you can also generate a cover
+   letter to explain the changes by adding the ``--cover-letter`` option.
+
+
+#. If you are happy that everything looks good you can sent the patch to the
+   DPDK ``dev`` mailing list::
+
+      git send-mail --to dev@dpdk.org 0001-doc-fix-minor-typo-etc.patch
+
+   If you have issues see the `git send-mail
+   <http://git-scm.com/docs/git-send-email>`_ section of the the Git
+   documentation.
+
+   If all goes well the patch will appear on the `DPDK dev mailing list
+   <http://dpdk.org/ml/listinfo/dev>`_ and in the `DPDK Patchwork
+   <http://dpdk.org/dev/patchwork/project/dpdk/list/>`_.
diff --git a/doc/guides/guidelines/index.rst b/doc/guides/guidelines/index.rst
index bfb9fa3..1050d99 100644
--- a/doc/guides/guidelines/index.rst
+++ b/doc/guides/guidelines/index.rst
@@ -8,3 +8,5 @@ Guidelines
     coding_style
     design
     versioning
+    documentation
+
-- 
1.8.1.4