[Notes] [Git][BuildStream/buildstream][master] CONTRIBUTING.rst: Added m

Tristan Van Berkom pushed to branch master at BuildStream / buildstream

Commits:

c31ed138

by Tristan Van Berkom at 2018-10-14T15:24:53Z

CONTRIBUTING.rst: Added more guidelines about documenting the user guide

4 changed files:

CONTRIBUTING.rst
doc/source/main_using.rst
doc/source/using_examples.rst
doc/source/using_tutorial.rst

Changes:

CONTRIBUTING.rst

@@ -1147,7 +1147,7 @@ To actually regenerate the code::
  Documenting
  -----------
  BuildStream starts out as a documented project from day one and uses
 -sphinx to document itself.
 +`sphinx <www.sphinx-doc.org>`_ to document itself.
  This section discusses formatting policies for editing files in the
  ``doc/source`` directory, and describes the details of how the docs are
@@ -1194,10 +1194,8 @@ The BuildStream documentation style is as follows:
      the target, e.g.: ``:ref:`Link text <anchor_name>```.
      Note that the "_" prefix is not used when referring to the target.
 -Useful links:
+-
 -For further information, please see the `Sphinx Documentation
 -<http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
 +For further information about using the reStructuredText with sphinx, please see the
 +`Sphinx Documentation <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
  Building Docs
@@ -1266,10 +1264,101 @@ the ``man/`` subdirectory, which will be automatically included
  in the buildstream distribution.
 -Documentation Examples
 -~~~~~~~~~~~~~~~~~~~~~~
 -The examples section of the documentation contains a series of standalone
 -examples, here are the criteria for an example addition.
 +User guide
 +~~~~~~~~~~
 +The :ref:`user guide <using>` is comprised of free form documentation
 +in manually written ``.rst`` files and is split up into a few sections,
 +of main interest are the :ref:`tutorial <tutorial>` and the
 +:ref:`examples <examples>`.
++
 +The distinction of the two categories of user guides is important to
 +understand too.
++
 +* **Tutorial**
++
 +  The tutorial is structured as a series of exercises which start with
 +  the most basic concepts and build upon the previous chapters in order
 +  to arrive at a basic understanding of how to create BuildStream projects.
++
 +  This series of examples should be easy enough to complete in a matter
 +  of a few hours for a new user, and should provide just enough insight to
 +  get the user started in creating their own projects.
++
 +  Going through the tutorial step by step should also result in the user
 +  becoming proficient enough with the reference manual to get by on their own.
++
 +* **Examples**
++
 +  These exist to demonstrate how to accomplish more advanced tasks which
 +  are not always obvious and discoverable.
++
 +  Alternatively, these also demonstrate elegant and recommended ways of
 +  accomplishing some tasks which could be done in various ways.
++
++
 +Guidelines
 +''''''''''
 +Here are some general guidelines for adding new free form documentation
 +to the user guide.
++
 +* **Focus on a single subject**
++
 +  It is important to stay focused on a single subject and avoid getting
 +  into tangential material when creating a new entry, so that the articles
 +  remain concise and the user is not distracted by unrelated subject material.
++
 +  A single tutorial chapter or example should not introduce any additional
 +  subject material than the material being added for the given example.
++
 +* **Reuse existing sample project elements**
++
 +  To help avoid distracting from the topic at hand, it is always preferable to
 +  reuse the same project sample material from other examples and only deviate
 +  slightly to demonstrate the new material, than to create completely new projects.
++
 +  This helps us remain focused on a single topic at a time, and reduces the amount
 +  of unrelated material the reader needs to learn in order to digest the new
 +  example.
++
 +* **Don't be redundant**
++
 +  When something has already been explained in the tutorial or in another example,
 +  it is best to simply refer to the other user guide entry in a new example.
++
 +  Always prefer to link to the tutorial if an explanation exists in the tutorial,
 +  rather than linking to another example, where possible.
++
 +* **Link into the reference manual at every opportunity**
++
 +  The format and plugin API is 100% documented at all times. Whenever discussing
 +  anything about the format or plugin API, always do so while providing a link
 +  into the more terse reference material.
++
 +  We don't want users to have to search for the material themselves, and we also
 +  want the user to become proficient at navigating the reference material over
 +  time.
++
 +* **Use concise terminology**
++
 +  As developers, we tend to come up with code names for features we develop, and
 +  then end up documenting a new feature in an example.
++
 +  Never use a code name or shorthand to refer to a feature in the user guide, instead
 +  always use fully qualified sentences outlining very explicitly what we are doing
 +  in the example, or what the example is for in the case of a title.
++
 +  We need to be considerate that the audience of our user guide is probably a
 +  proficient developer or integrator, but has no idea what we might have decided
 +  to name a given activity.
++
++
 +Structure of an example
 +'''''''''''''''''''''''
 +The :ref:`tutorial <tutorial>` and the :ref:`examples <examples>` sections
 +of the documentation contain a series of sample projects, each chapter in
 +the tutoral, or standalone example uses a sample project.
++
 +Here is the the structure for adding new examples and tutorial chapters.
  * The example has a ``${name}``.
@@ -1280,11 +1369,17 @@ examples, here are the criteria for an example addition.
  * The example has a documentation component.
    * This is added at ``doc/source/examples/${name}.rst``
 -  * A reference to ``examples/${name}`` is added to the toctree in ``doc/source/examples.rst``
 +  * An entry for ``examples/${name}`` is added to the toctree in ``doc/source/using_examples.rst``
    * This documentation discusses the project elements declared in the project and may
      provide some BuildStream command examples.
    * This documentation links out to the reference manual at every opportunity.
 +  .. note::
++
 +     In the case of a tutorial chapter, the ``.rst`` file is added in at
 +     ``doc/source/tutorial/${name}.rst`` and an entry for ``tutorial/${name}``
 +     is added to ``doc/source/using_tutorial.rst``.
++
  * The example has a CI test component.
    * This is an integration test added at ``tests/examples/${name}``.

doc/source/main_using.rst

 +.. _using:
++
  Using
  =====
  This section includes user facing documentation including tutorials,

doc/source/using_examples.rst

++
 +.. _examples:
++
  Examples
  ========
  This page contains documentation for real examples of BuildStream projects,

doc/source/using_tutorial.rst

++
 +.. _tutorial:
++
  Tutorial
  ========
  This is a step by step walkthrough meant help the user quickly get

[Notes] [Git][BuildStream/buildstream][master] CONTRIBUTING.rst: Added more guidelines about documenting the user guide

Tristan Van Berkom pushed to branch master at BuildStream / buildstream

Commits:

4 changed files:

Changes: