Merge pull request #40 from clearlinux/doc-guide

Add documentation contribution guidelines.
2026-08-25 17:45:52 +00:00 · 2017-12-11 12:06:13 -06:00
parent 35ea5f2e1b 9a876dd542
commit c840c721d2
23 changed files with 2335 additions and 1 deletions
@@ -0,0 +1,18 @@
+.. _collaboration:
+
+Collaboration guidelines
+########################
+
+Thank you for your interest in collaborating with the |CLOSIA|. This guide
+details the best ways to communicate and collaborate with the |CL| team.
+Additionally, this guide provides the guidelines our documentation follows.
+Thus, you can help improve our documents with your use case tutorials,
+examples, or task focused guides. Read the information carefully before
+submitting any work for review to ensure your contribution can be added as
+quickly as possible.
+
+.. toctree::
+   :maxdepth: 1
+
+
+   documentation/documentation
@@ -0,0 +1,130 @@
+.. _basic:
+
+Basic contribution guide
+########################
+
+This list compiles the most common format, markup, structure, and grammar
+rules for your convenience. You can find more detailed information in the
+referenced sections.
+
+.. contents::
+   :local:
+   :backlinks: entry
+
+Format
+******
+
+* Limit line length to 78 characters. The GitHub web interface forces this
+  limitation for readability.
+
+* Remove trailing white space from your documents.
+
+* Use short sentences and paragraphs. Keep sentence length under 20 words.
+
+* Use only lower case letters for filenames.
+
+* Separate multiple words in filenames using dashes.
+
+Markup
+******
+
+* Use the appropriate :abbr:`ReST (ReStructuredText)` roles for your content.
+  See the `ReST primer`_ for the complete list of roles.
+
+* Use the :abbr: role to define the first instance of an abbreviation, for
+  example: :abbr:\`CL (Clear Linux)\`.
+
+* Use hash-tags to underline the file's main title.
+
+* Use asterisks to underline the file's first level headings.
+
+* Use equal signs to underline the file's second level of headings.
+
+* Use dashes to underline the file's third level of headings.
+
+* Use labels to reference documentation sections. Do not reference
+  sections with URLs. See :ref:`cross` for details.
+
+* Don't use explicit URLs as links, for example https://clearlinux.org/.
+
+* Always include descriptive link text. For example:
+  Visit the `Clear Linux website`_. Do not use "here", "this", or similar
+  references for link text.
+
+Structure
+*********
+
+* All files must have a main title and up to three levels of headings.
+  Restructure the content in multiple files as needed to comply.
+
+* Use descriptive headings.
+
+* Follow all headings with at least one paragraph of content. There should
+  never be two consecutive headings.
+
+* Separate the link and the target definition. All target definitions must be
+  included at the end of the file. See :ref:`cross` for details.
+
+* Use parallelism in headings, sentences, and lists. See our
+  :ref:`parallelism` for details.
+
+* Put conditional phrases first in cautions and warnings. For example:
+  "If you do X, then Y will occur." See our :ref:`notices` guide.
+
+* Place figures and tables immediately after related text.
+
+* Place code or commands immediately after the leading text in a new line,
+  see our :ref:`code`.
+
+* Reference figures, code examples, and tables by number.
+  For example, use "Figure 1," instead of "The figure above or below". See
+  :ref:`cross` and :ref:`images`.
+
+* Include at least one direct reference to any table or figure you add. See
+  :ref:`tables`.
+
+Grammar
+*******
+
+* Include only one main idea in a sentence. See :ref:`simple`.
+
+* Limit the number of clauses you use to no more than two. See :ref:`simple`.
+
+* Limit the number of sentences per paragraph to about six. See :ref:`simple`.
+
+* Use strong verbs. See :ref:`simple`.
+
+* Use action verbs. See :ref:`simple`.
+
+* Avoid weak verbs like be, have, make, and do. See :ref:`simple`.
+
+* Use short direct commands and avoid niceties such as the word
+  "please".
+
+* Use the present tense wherever possible and avoid past and future
+  tense verbs. See :ref:`simple`.
+
+* Use Active voice. Write, "Someone does something"; don't write,
+  "Something is done by someone" or "Something is done." See :ref:`simple`.
+
+* Use "we" for recommendations. Write "We recommend..." as opposed to
+  "It is recommended...." See :ref:`simple`.
+
+* Use "you" rather than "the user" in your instructions.
+
+* Use short common English words whenever possible, see our :ref:`simple`
+  guide.
+
+* Avoid contractions. See :ref:`grammar`.
+
+* Use articles such as 'a', 'an', and 'the' to reduce ambiguity.
+
+Additional information
+**********************
+
+Learn more about the accepted rules of grammar, punctuation, and word use in
+our :ref:`language`. If you are looking for tips on how to write shorter,
+clearer, and more concise content, visit our :ref:`simple` guide.
+
+.. _Clear Linux website: https://clearlinux.org/
+.. _ReST primer: http://docutils.sourceforge.net/docs/user/rst/quickstart.html
@@ -0,0 +1,161 @@
+.. _code:
+
+Code blocks
+###########
+
+Collaborating to the |CLOSIA| is all about code. Therefore, your
+documentation must include as many code examples as possible. You can write
+code examples directly in the documentation or include them from a source
+file. Use these guidelines to insert code blocks to your documentation:
+
+* Include code examples from a source file. Only write the code example
+  directly into the documentation if the example is less than 10 lines long.
+
+* Use the ``:linenos:`` option of the `literalinclude` directive to add line
+  numbers to your example.
+
+* Specify the programing language of your example. Not only will it
+  add syntax highlighting but it also allows the reader to identify code
+  efficiently. Use `bash` for console commands, `asm` for assembly code and
+  `c` for C code.
+
+* Treat all console commands entered by users as code examples.
+
+Examples
+********
+
+This is a code example included from a file. Note how only certain lines of
+the source file are included and how the lines are renumbered.
+
+This source:
+
+.. code-block:: rst
+
+   .. literalinclude:: ./hello.c
+      :language: c
+      :lines: 97-110
+      :linenos:
+
+Renders as:
+
+.. literalinclude:: ./hello.c
+   :language: c
+   :lines: 97-110
+   :linenos:
+
+
+This example shows a series of console commands. Line numbering is not
+required. Specify that these are commands using `bash` as the programing
+language.
+
+This source:
+
+.. code-block:: rst
+
+   .. code-block:: bash
+
+      $ mkdir ${HOME}/x86-build
+
+      $ mkdir ${HOME}/arm-build
+
+      $ mkdir ${HOME}/cross-src
+
+Renders as:
+
+.. code-block:: bash
+
+   $ mkdir ${HOME}/x86-build
+
+   $ mkdir ${HOME}/arm-build
+
+   $ mkdir ${HOME}/cross-src
+
+.. note::
+   You will find instances which use `console` instead of `bash`. We are
+   currently in the process of implementing a distinction between the two.
+   Moving forward, `bash` will be used for commands entered by readers, and
+   `console` will be used for the output users obtain in the command prompt.
+
+Finally, this is a code example that is not part of the |CL| code base. It is
+not even valid code but it can illustrate the concept.
+
+This source:
+
+.. code-block:: rest
+
+   .. code-block:: c
+
+      static NANO_CPU_INT_STUB_DECL (deviceStub);
+
+      void deviceDriver (void)
+
+      {
+
+      .
+      .
+      .
+
+      nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler,
+      deviceStub);
+
+      .
+      .
+      .
+
+      }
+
+Renders as:
+
+.. code-block:: c
+
+   static NANO_CPU_INT_STUB_DECL (deviceStub);
+
+   void deviceDriver (void)
+
+   {
+
+   .
+   .
+   .
+
+   nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler,
+   deviceStub);
+
+   .
+   .
+   .
+
+   }
+
+Templates
+*********
+
+We included templates for a basic ``.. code-block::`` directive
+and for a ``.. literalinclude::`` directive.
+
+Use ``code-block`` for console commands, brief examples, and examples
+outside the |CL| code base.
+
+.. code-block:: rst
+
+   .. code-block:: language
+
+      source
+
+Use ``litteralinclude`` to insert code from a source file. Keep in
+mind that you can include the entire contents of the file or just
+specific lines.
+
+.. code-block:: rst
+
+   .. literalinclude:: ../path/to/file/file_name.c
+      :language: c
+      :lines: 5-30, 32, 70-100
+      :emphasize-lines: 3
+      :linenos:
+
+.. caution::
+   The ``:emphasize-lines:`` option uses the line numbering provided
+   by ``:linenos:``. The emphasized line in the template will be the
+   third one of the example but the eighth one of the source file.
+
@@ -0,0 +1,124 @@
+.. _cross:
+
+Cross-references
+################
+
+Sphinx provides different methods to create both internal and
+external cross-references. Use only the following methods to increase the
+consistency of the documents.
+
+.. _internal-cross:
+
+Internal cross-references
+*************************
+
+An internal cross-reference is a reference to a location within the |CLOSIA|
+documentation. Use explicit markup labels and the ``:ref:`` role to create
+cross references to headings, figures, and code examples as needed. Every
+file must have a label before the title identical to the file's name in order
+to be able to add cross-references without having to open the file.
+
+The labels' naming conventions are:
+
+* Use only full words.
+
+* Use \- to link multiple words.
+
+* Use only as many words as necessary to ensure the label is unique.
+
+These are some examples of proper labels:
+
+.. code-block:: rst
+
+   .. _quick-start:
+
+   .. _gerrit-access:
+
+   .. _building-clear-linux:
+
+Do not use labels like these:
+
+.. code-block:: rst
+
+   .. _QuickStart:
+
+   .. _How to Gain Access to Gerrit:
+
+   .. _building:
+
+As an example, this is an internal reference to the beginning of the :ref:`rest`.
+
+Observe that the ``:ref:`` role is replaced with the title's text.
+Similarly, it will be replaced with the figure's caption. If a different
+text is needed the ``:ref:`` role can still be used, for example:
+
+This is an internal reference to the beginning of
+:ref:`this section <rest>`.
+
+Use the following templates to insert internal cross references properly.
+
+.. code-block:: rst
+
+   .. _label-of-target:
+
+   This is a heading
+   -----------------
+
+   This creates a link to the :ref:`label-of-target` using the text of the
+   heading.
+
+   This creates a link to the :ref:`target <label-of-target>` using the word
+   'target' instead of the heading.
+
+The template renders as:
+
+.. _label-of-target:
+
+This is a heading
+-----------------
+
+This creates a link to the :ref:`label-of-target` using the text of the
+heading.
+
+This creates a link to the :ref:`target <label-of-target>` using the word
+'target' instead of the heading.
+
+.. note::
+
+   This type of internal cross reference works across multiple files, is
+   independent of changes in the text of the headings, and works on all
+   Sphinx builders.
+
+External References
+*******************
+
+External references or hyperlinks can be added easily with ReST. Only
+hyperlinks with a separated target definition are allowed.
+
+Do not use explicit hyperlinks consisting entire URLs. For example, links
+like this one, https://clearlinux.org/ must be avoided.
+
+Hyperlinks with a separated target definition allow us to place the URL after
+label. They are easier to update and independent of the text, for example:
+
+`Gitg`_ is a great tool to visualize a GIT tree.
+
+.. _Gitg: https://wiki.gnome.org/Apps/Gitg/
+
+Follow these guidelines when inserting hyperlinks:
+
+* The labels for hyperlinks must be grammatically correct and unique within
+  the file.
+
+* Do not create labels for hyperlinks using: link, here, this, there, etc.
+
+* Add all target definitions at the end of the file containing the
+  hyperlinks.
+
+Use this template to add a hyperlink with a separated definition:
+
+.. code-block:: rst
+
+   The state of `Oregon`_ offers a wide range of recreational activities.
+
+   .. _Oregon: http://traveloregon.com/
@@ -0,0 +1,138 @@
+.. _documentation:
+
+Documentation contribution guidelines
+#####################################
+
+The |CLOSIA| documentation contribution guidelines provide detailed information
+about the scope and purpose of the documentation, the accepted writing style,
+and the markup used.
+
+The |CL| documentation is hosted in GitHub and welcomes community
+contributions. This guide provides rules to write
+:ref:`clear, concise<basic>`, and :ref:`consistent content<structures>`. Our
+documentation is written using ReStructuredText and we provide
+:ref:`examples, templates, and best practices<rest>` for that markup.
+
+To contribute, follow the standard `GitHub flow`_:
+
+#. Clone the `Clear Linux 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 section`_.
+
+The |CL| technical content is written in simple American English and our
+:ref:`language` contains detailed information on that standard.
+
+This guide includes the following sections:
+
+.. toctree::
+   :maxdepth: 2
+
+   basic
+   structures
+   rest
+   language
+
+
+Scope
+*****
+
+The |CL| documentation is divided in five sections:
+
+* **Get started:** Information about installing Clear Linux.
+* **Concepts:** Detailed technical information about our features.
+* **Guides:** Step-by-step instructions to complete common tasks and
+  configuration.
+* **Tutorials:** Step-by-step instructions to complete the installation and
+  configuration of the tools needed for a specific use case.
+* **Reference:** Information providing additional context or details.
+
+If you are unsure on which section to use for your contribution, send an
+email to our `mailing list`_ at: dev@lists.clearlinux.org Include the outline
+of the contribution you are planning and a brief description of its intended
+purpose and scope.
+
+This style guide applies to the following technical content:
+
+* Commit messages
+* Technical presentations
+* All documents in ReStructuredText within and without the documentation
+  repository
+* In-code comments
+* Release notes
+
+We are always grateful to receive content contributions and are happy to help
+via our mailing list or our IRC channel, #clearlinux. If you have found a
+problem with one of our documents, please file a bug report. Use our
+:ref:`bug-report` to submit the bug.
+
+Tone and audience
+*****************
+
+The tone of the |CL| documentation should be clear, concise, confident, and
+courteous. We write for our peers and want to be familiar. Use the second
+person, you or we, and active voice, we configure or you run, for example.
+Remain professional in your writing and carry an undertone of cordiality,
+respect, and cooperation.
+
+Assume your audience has about the same level of technical understanding and
+expertise as you did when you first started collaborating. Do not talk down to
+our readers but do not assume they know everything about the subject.
+Offer brief explanations or summaries of "common knowledge" if a
+significant portion of readers might benefit.
+
+All contributions must follow our :ref:`code-of-conduct`.
+
+Methodology
+***********
+
+This guide differs from other style guides and contains additional material
+not found in those sources.
+
+To research a style question, look for the answer in this guide
+first. If the question is not answered here, send your question to the
+`mailing list`_ at: dev@lists.clearlinux.org.
+
+If the question is answered in the existing style guide or dictionary,
+the solution is implemented and enforced as described.
+
+References
+**********
+
+In creating and refining the policies in this document, we consulted the
+following sources for guidance:
+
+* The Chicago Manual of Style (15th edition), The University of
+  Chicago Press;
+* Merriam-Webster Dictionary;
+* Microsoft Manual of Style for Technical Publications, Microsoft
+  Press;
+* Microsoft Press Computer Dictionary, Microsoft Press; and
+* Read Me First!, Oracle Technical Publications.
+
+These sources do not always concur on questions of style and usage; nor do we
+always agree with these sources. In areas where there is disagreement, the
+decisions are explained in the respective section.
+
+This guide takes precedence over all other style guides in all cases. In
+cases where the guide does not address the issue at hand, please report the
+issue to the `mailing list`_ using our :ref:`bug-report`.
+
+Use the Merriam-Webster's Collegiate Dictionary to determine correct
+spelling, hyphenation, and usage.
+
+.. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev
+.. _GitHub flow: https://guides.github.com/introduction/flow/
+.. _documentation section: https://clearlinux.org/documentation
+.. _Clear Linux documentation repository:
+   https://github.com/clearlinux/clear-linux-documentation
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="106.55701"
+   height="106.49829"
+   id="svg5827"
+   version="1.1"
+   inkscape:version="0.48.5 r10040"
+   sodipodi:docname="Fibers.svg">
+  <defs
+     id="defs3" />
+  <sodipodi:namedview
+     inkscape:document-units="mm"
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="138.72634"
+     inkscape:cy="23.280168"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="mm"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     inkscape:window-width="1920"
+     inkscape:window-height="1017"
+     inkscape:window-x="-8"
+     inkscape:window-y="-8"
+     inkscape:window-maximized="1" />
+  <metadata
+     id="metadata4">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-320.92486,-84.790913)">
+    <g
+       transform="translate(111.50953,81.385786)"
+       style="font-size:12px;fill:none;stroke-linecap:square;stroke-miterlimit:3;overflow:visible"
+       id="g5872">
+      <path
+         inkscape:connector-curvature="0"
+         style="fill:#686868;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         d="m 315.97234,56.654274 c 0,0.176127 0,0.293546 0,0.410964 -0.0587,6.751545 -1.40902,13.209546 -3.69868,19.080455 -0.11742,0.293545 -0.23483,0.587091 -0.35225,0.880636 -1.99611,4.872855 -4.75544,9.452164 -8.10186,13.503092 -0.29354,0.352254 -0.52838,0.6458 -0.82192,0.998054 -1.40902,1.585146 -2.87675,3.111582 -4.46189,4.5206 -0.29355,0.293546 -0.6458,0.587091 -0.93935,0.821928 -4.16835,3.639967 -8.92378,6.692837 -14.09018,8.865077 -0.29355,0.11741 -0.58709,0.23483 -0.82193,0.35225 -6.04704,2.40707 -12.68116,3.81609 -19.55013,3.81609 -0.17612,0 -0.29354,0 -0.46967,0 -0.11742,0 -0.23484,0 -0.41096,0 -6.86897,0 -13.5031,-1.40902 -19.55013,-3.81609 -0.23484,-0.11742 -0.52838,-0.23484 -0.82193,-0.35225 -5.1664,-2.17224 -9.92184,-5.22511 -14.09018,-8.865077 -0.29355,-0.234837 -0.58709,-0.528382 -0.93935,-0.821928 -1.58514,-1.409018 -3.05287,-2.935454 -4.46189,-4.5206 -0.29354,-0.352254 -0.52838,-0.6458 -0.82193,-0.998054 -3.34641,-4.050928 -6.10574,-8.630237 -8.10185,-13.503092 -0.11742,-0.293545 -0.23484,-0.587091 -0.35225,-0.880636 -2.28966,-5.870909 -3.63997,-12.32891 -3.69868,-19.080455 0,-0.117418 0,-0.234837 0,-0.410964 0,-0.117418 0,-0.234836 0,-0.410963 0.0587,-6.751546 1.40902,-13.150837 3.69868,-19.080455 0.11741,-0.293546 0.23483,-0.528382 0.35225,-0.821928 1.99611,-4.931564 4.75544,-9.452164 8.10185,-13.5618 0.29355,-0.293546 0.52839,-0.587091 0.82193,-0.939346 1.40902,-1.643854 2.87675,-3.170291 4.46189,-4.579309 0.35226,-0.293545 0.6458,-0.587091 0.93935,-0.821927 4.16834,-3.639964 8.92378,-6.6341276 14.09018,-8.806364 0.29355,-0.1761273 0.58709,-0.2348364 0.82193,-0.3522545 6.04703,-2.4657819 12.68116,-3.816091 19.55013,-3.8748001 0.17612,0 0.29354,0 0.41096,0 0.17613,0 0.29355,0 0.46967,0 6.86897,0.058709 13.50309,1.4090182 19.55013,3.8748001 0.23484,0.1174181 0.52838,0.1761272 0.82193,0.3522545 5.1664,2.1722364 9.92183,5.1664 14.09018,8.806364 0.29355,0.234836 0.6458,0.528382 0.93935,0.821927 1.58514,1.409018 3.05287,2.935455 4.46189,4.579309 0.29354,0.352255 0.52838,0.6458 0.82192,0.939346 3.34642,4.109636 6.10575,8.630236 8.10186,13.5618 0.11742,0.293546 0.23483,0.528382 0.35225,0.821928 2.28966,5.929618 3.63997,12.387618 3.69868,19.080455 0,0.176127 0,0.293545 0,0.410963"
+         id="path5409" />
+      <path
+         inkscape:connector-curvature="0"
+         style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         d="m 315.97234,56.654274 c 0,0.176127 0,0.293546 0,0.410964 l -106.55701,0 c 0,-0.117418 0,-0.234837 0,-0.410964 0,-0.117418 0,-0.234836 0,-0.410963 l 106.55701,0 c 0,0.176127 0,0.293545 0,0.410963 z"
+         id="path5415" />
+      <g
+         id="g5808">
+        <path
+           id="path5411"
+           d="m 298.53574,96.048075 c -0.29355,0.293546 -0.6458,0.587091 -0.93935,0.821928 l -69.80511,0 c -0.29355,-0.234837 -0.58709,-0.528382 -0.93935,-0.821928 l 71.68381,0 z"
+           style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5413"
+           d="m 312.27366,76.145693 c -0.11742,0.293545 -0.23483,0.587091 -0.35225,0.880636 l -98.45515,0 c -0.11742,-0.293545 -0.23484,-0.587091 -0.35225,-0.880636 l 99.15965,0 z"
+           style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5417"
+           d="m 312.27366,37.162856 -99.15965,0 c 0.11741,-0.293546 0.23483,-0.528382 0.35225,-0.821928 l 98.45515,0 c 0.11742,0.293546 0.23483,0.528382 0.35225,0.821928 z"
+           style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5419"
+           d="m 298.53574,17.260473 -71.68381,0 c 0.35226,-0.293545 0.6458,-0.587091 0.93935,-0.821927 l 69.80511,0 c 0.29355,0.234836 0.6458,0.528382 0.93935,0.821927 z"
+           style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5421"
+           d="m 303.81955,22.779128 0,67.750293 c -0.29354,0.352254 -0.52838,0.6458 -0.82192,0.998054 l 0,-69.687693 c 0.29354,0.352255 0.52838,0.6458 0.82192,0.939346 z"
+           style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5423"
+           d="m 283.50621,7.632182 0,98.102898 c -0.29355,0.11741 -0.58709,0.23483 -0.82193,0.35225 l 0,-98.8074025 c 0.23484,0.1174181 0.52838,0.1761272 0.82193,0.3522545 z"
+           style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5425"
+           d="m 263.13415,3.4051274 0,106.4982926 c -0.17612,0 -0.29354,0 -0.46967,0 -0.11742,0 -0.23484,0 -0.41096,0 l 0,-106.4982926 c 0.17612,0 0.29354,0 0.41096,0 0.17613,0 0.29355,0 0.46967,0 z"
+           style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5427"
+           d="m 242.70339,7.2799275 0,98.8074025 c -0.23484,-0.11742 -0.52838,-0.23484 -0.82193,-0.35225 l 0,-98.102898 c 0.29355,-0.1761273 0.58709,-0.2348364 0.82193,-0.3522545 z"
+           style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5429"
+           d="m 222.39004,21.839782 0,69.687693 c -0.29354,-0.352254 -0.52838,-0.6458 -0.82193,-0.998054 l 0,-67.750293 c 0.29355,-0.293546 0.52839,-0.587091 0.82193,-0.939346 z"
+           style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5431"
+           d="m 231.54866,35.812546 0,55.01042 62.23164,0 0,-55.01042 -62.23164,0 z"
+           style="fill:#f2f2f2;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5433"
+           d="m 238.82859,46.732438 0,4.227054 47.73049,0 0,-4.227054 -47.73049,0 z"
+           style="fill:#ead57d;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5435"
+           d="m 241.76404,39.511219 c 0.6458,0 0.76322,0.469673 0.46968,0.880637 l -2.5832,3.346418 c -0.29355,0.410964 -0.88064,0.469673 -1.2329,0 l -2.52449,-3.346418 c -0.35225,-0.469673 -0.17612,-0.880637 0.41097,-0.880637 l 5.45994,0 z"
+           style="fill:#c2c2c2;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5437"
+           d="m 238.82859,63.347111 0,4.168345 47.73049,0 0,-4.168345 -47.73049,0 z"
+           style="fill:#19d77a;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5439"
+           d="m 241.76404,56.125892 c 0.6458,0 0.76322,0.410964 0.46968,0.821928 l -2.5832,3.346418 c -0.29355,0.469673 -0.88064,0.469673 -1.2329,0 l -2.52449,-3.346418 c -0.35225,-0.469673 -0.17612,-0.821928 0.41097,-0.821928 l 5.45994,0 z"
+           style="fill:#c2c2c2;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5441"
+           d="m 238.82859,79.961784 0,4.168345 47.73049,0 0,-4.168345 -47.73049,0 z"
+           style="fill:#f0553a;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <path
+           id="path5443"
+           d="m 241.76404,72.740566 c 0.6458,0 0.76322,0.352254 0.46968,0.821927 l -2.5832,3.287709 c -0.29355,0.410964 -0.88064,0.410964 -1.2329,0 l -2.52449,-3.287709 c -0.35225,-0.469673 -0.17612,-0.821927 0.41097,-0.821927 l 5.45994,0 z"
+           style="fill:#c2c2c2;fill-opacity:1;fill-rule:evenodd;stroke:none"
+           inkscape:connector-curvature="0" />
+        <text
+           id="text5445"
+           style="font-size:17.8475647px;font-style:normal;font-weight:normal;text-align:start;text-anchor:start;fill:#ffffff;font-family:Intel Clear"
+           y="30.496477"
+           x="238.84772"
+           xml:space="preserve">Fibers</text>
+      </g>
+    </g>
+  </g>
+</svg>
@@ -0,0 +1,342 @@
+.. _grammar:
+
+Grammar guide
+#############
+
+This guide provides valuable insight into the correct grammar for the
+|CLOSIA| documentation. It covers subjects such as capitalization, verbs,
+hyphenation, possessives, and contractions.
+
+Capitalization
+**************
+
+The preferred capitalization style for all documentation is sentence
+case.
+
+Words should only be capitalized when:
+
+* They are proper nouns or adjectives.
+* They refer to trademarked product names.
+
+.. note::
+   Do not capitalize a word to indicate it has a greater status than other
+   words. Never change the case of variable, function or file names; always
+   keep the original case.
+
+Menu capitalization
+===================
+
+When referring to software menu items by name, replicate the
+capitalization as it appears in the software menus the user will see.
+It is acceptable to refer to these items generically by using
+lowercase letters if it is clear that your reference is generic and
+not a specific name of a window or field on a menu, for example:
+
+Click :guilabel:`Edit` to display the :guilabel:`Widget Configuration` window.
+
+The widget configuration window has several advanced widget configuration
+options.
+
+The second sentence could have capitalized the term "Widget
+Configuration window"; but there are times when you might want to
+refer to something with a generic descriptor and not its name. Observe
+the use of the ReST markup ``:guilabel:`` on the first sentence.
+
+A few other menu capitalization rules to keep in mind:
+
+* Use "Select :menuselection:`File --> New`."
+
+* Put the option to be selected last. "Select
+  :menuselection:`View --> Side Bar --> Hide Side Bar`"
+
+* Do not include more than 3 navigation steps in a menu selection. If
+  more than three steps are needed divide the steps using
+  ``:guilabel:`` or ``:menuselection:``. For example: "Go to
+  :guilabel:`File` and select
+  :menuselection:`Print --> Print Preview --> Set Up`."
+
+Software version capitalization
+===============================
+
+Do not capitalize the word version or letter v when listing software
+or hardware version numbers. The v is lowercase and closed with the
+number (no period). For example:
+
+* Widget Pro v5.0
+* Widget Master v2.1.12
+
+Hyphenated or slashed-concatenated terms
+========================================
+
+For hyphenated or slash-concatenated terms, capitalize only the first
+letter, even if they are headings. For example:
+
+* Day/night Menu
+* Follow-up Action Items
+
+Plurals and possessives
+***********************
+
+Because English plurals and possessives use the same /s/ and /z/
+phonemes, they can create problems for even experienced writers. This
+section deals with these issues.
+
+Singular vs. plural possessives
+===============================
+
+Here are some guidelines for singular and plural possessives:
+
+* Use only the apostrophe to show possession for a plural that ends in
+  s: The boys' books.
+
+* Use apostrophe + s to show possession for a plural that does not end
+  in s: The men's books.
+
+* Use apostrophe + s to show possession for a singular that ends in a
+  silent sibilant: Illinois's capital.
+
+* Use apostrophe + s to show
+  possession for a singular that ends in a sibilant; s, x, c, z, or
+  others.
+
+The following table provides some examples with the correct and
+incorrect cases and the notes that accompanies them.
+
+-------------------+------------------+---------------------------+
+| Correct           | Incorrect        | Notes                     |
+===================+==================+===========================+
+| the boys' books   | the boy's books  | The books that belong to  |
+|                   |                  | several boys.             |
+-------------------+------------------+---------------------------+
+| the men's books   | the mens' books  | The books that belong to  |
+|                   |                  | several men.              |
+|                   |                  |                           |
+-------------------+------------------+---------------------------+
+| Arkansas's code   | Arkansas' code   | The s at the end of       |
+|                   |                  | Arkansas is silent and    |
+|                   |                  | Arkansas is not a plural. |
+-------------------+------------------+---------------------------+
+| the boss's office | the boss' office | We say: "the /BOSS-iz/    |
+|                   |                  | office" not "the/BOSS/    |
+|                   |                  | office."                  |
+-------------------+------------------+---------------------------+
+| the box's lid     | the boxe's lid   | One could say "the box    |
+|                   | the box' lid     | lid," avoiding the        |
+|                   |                  | possessive.               |
+-------------------+------------------+---------------------------+
+| Lopez's average   | Lopez' average   | We say "/LO-pez-iz/       |
+|                   |                  | average," not "/LO-pez/   |
+|                   |                  | average."                 |
+-------------------+------------------+---------------------------+
+| business's sales  | business' sales  | If you pronounce another  |
+|                   |                  | syllable to show          |
+|                   |                  | possession, it must have  |
+|                   |                  | the apostrophe-s.         |
+-------------------+------------------+---------------------------+
+
+Apostrophe-s anomalies
+======================
+
+If a company name ends in s, x, c, or a sibilant sound, use the
+apostrophe-s ending for
+possessives:
+
+Traktronix's oscilloscopes
+
+Exception: If the company name is intended as a plural, we allow the
+apostrophe-only ending:
+
+Tejada Instruments' calculators
+
+In many cases, it is actually best to avoid the possessive form
+altogether for s-ending singular possessives, such as for company
+names and use the company name as a nonpossessive modifier instead:
+
+Traktronix oscilloscopes
+Tejada Instruments calculators
+
+We say "Intel equipment" when discussing Intel-branded products, not
+"Intel's equipment", which implies that we own it, not that we produce
+it. "Intel's equipment" sounds like the equipment that Intel employees
+use.
+
+Plural modifiers
+================
+
+Avoid plural modifiers. For example, it should be a system
+administrator, not a systems administrator. It doesn't matter how many
+systems this person manages, we don't typically use the plural of a word
+to modify a noun. Here is a list of exceptions:
+
+* operations manager
+* sales department
+* graphics team
+
+
+There are always exceptions, especially when the plural form is
+generally considered to be singular: sales, physics, operations. It is
+best to adhere to this rule and ask if you are unsure.
+
+Parenthetical plurals
+=====================
+
+Do not parenthesize optional plurals, whether added to the end of a
+word, typically with the letter s, or internally. In general, think in
+plurals when you write, assume that the user understands that a plural
+could mean a singular as well. A typical user who has only one unit
+will not be confused if you say "connect the units." On the contrary,
+using parenthetical plurals often creates more confusion.
+
+Correct
+
+Men, women, children, college alumni, moose,
+and even desert plants such as cacti should not
+use parentheses around plurals.
+
+Incorrect
+
+A m(e)n, wom(a)n, a child(ren), college alumn(i), (moose), and
+even a desert plant(s) such as a cact(i) should not use a
+parenthes(e)s around a plural(s).
+
+Internal plural acronyms
+========================
+
+Some abbreviated terms can cause trouble, particularly when the
+pluralized portion does not fall at the end of the phrase. These
+internal-plural words should follow standard English pluralization
+rules when abbreviated: The plural goes at the end of the term.
+
+* Alarms acknowledged and logged: AAL, AALs.
+* Attorneys-general: AG, AGs.
+* Regions of interest: ROI, ROIs.
+
+Plurals of acronyms and capitalized product names
+=================================================
+
+Pluralize acronyms, initialisms, and capitalized product names by
+adding a lowercase s; do not use an apostrophe. If the term ends in a
+sibilant (s, x, z, sometimes c and others), pluralize it by adding a
+lowercase es. Examples:
+
+Use TVs, DVDs, CDs, DVMRs not TV's, DVD's, CD's, DVMR's.
+Use OSes not OSs, OS's.
+Use TRAXes, iBOXes not TRAXs, TRAX's, iBOX's, iBOXs.
+Use FAACes not FAAC's, assuming it is pronounced "face".
+Use FAACs not FAAC's Assuming it is pronounced "fake".
+
+Whenever you hear the extra syllable in the plural, add the -es suffix
+for the plural; if you do not hear the extra syllable, add the -s
+suffix for the plural.
+
+Latin plurals
+=============
+
+Pluralize Latin terms in body text as shown:
+
+* Use appendixes not appendices.
+* Use matrixes not matrices.
+* Use indexes not indices.
+* Use vertexes not vertices.
+
+.. note::
+   Some Latin plurals, such as parentheses, phenomena, alumni, and
+   crises, are widely used and accepted in English.
+
+Contractions
+************
+
+Avoid the use of contractions since some of them might be ambiguous and
+confusing to non-native English-speaking audiences.
+
+Some contractions can cause confusion for non-native English-speakers
+because these contractions stand for more than one construction. For
+example, there's can be a contraction of there is or there has. The
+same applies to where's, it's, that's, and others.
+
+Also, avoid contractions of the word is, especially when combined with
+company or product names: Say, WidgetPro is an awesome product; not
+WidgetPro's an awesome product.
+
+Hyphenation
+***********
+
+The hyphen is often used to join words together to form a compound noun.
+Compound nouns often go through this progressions:
+
+* open compound: health care
+* hyphenated compound: health-care
+* closed compound: healthcare
+
+The English language is trending away from hyphenated compounds to
+closed compounds.
+
+Prefix hyphenation
+==================
+
+Do not hyphenate the prefixes listed below. Join the prefix to the
+term being modified, even if this results in a double vowel or double
+consonant:
+
+ante, counter, intra, mini, pro, super, anti, extra, meta, non,
+pseudo, trans, bi, by, infra, micro, post, re, ultra, bio, inter, mid,
+pre, sub, un.
+
+Here are some words that are often inappropriately hyphenated; do not
+hyphenate these words either:
+
+antitheft device, multicamera, multiscreen, prepackaged, reuse,
+submenu, autofocus, multifamily, multiuser, pseudoscience, semiannual,
+subtotal, autoiris, multimedia, nonprofit, reengineered, semicircle,
+superuser, microarchitecture, multiposition, predefined, reevaluate,
+subfolder, superscript, microorganism, multiprotocol, predrilled,
+reinvent, submarine.
+
+.. note::
+   Question whether the pre- prefix is needed at all and consider
+   leaving it off the word entirely if the meaning is the same.
+
+Exceptions
+----------
+
+One overriding exception to the prefix rule is when the prefix is
+prepended to a proper and capitalized noun:
+
+* Non-European
+* Mid-April (but: midweek)
+
+Another exception is when the second word of a compound is a numeral:
+
+* Pre-1914
+
+Some prefixes, such as self-, half-, quasi-, and ex-, when meaning
+"formerly", usually need a hyphen:
+
+* Self-control, half-truth, quasi-corporation, ex-governor
+
+Suffix hyphenation
+==================
+
+In general, do not hyphenate suffixes. Here are some examples.
+The suffix -wide is usually not hyphenated:
+
+* Nationwide, worldwide, systemwide, campuswide, statewide,
+  companywide, etc.
+
+The suffix -wise is usually not hyphenated:
+
+* Otherwise, businesswise, revenuewise, clockwise, counterclockwise
+
+
+Quotation marks
+***************
+
+Follow these guidelines for quotation marks:
+
+* Restrict use of quotation marks to terms as terms.
+* Do not use quotation marks for emphasis; use *italics* for emphasis.
+* Avoid using single-quote marks.
+* In terms of punctuation: commas and periods typically go inside the
+  end-quote; semicolons, colons, question marks, and exclamation points
+  typically go outside quotation marks. Unless they are part of the
+  actual quotation.
@@ -0,0 +1,30 @@
+.. _headings:
+
+Headings
+########
+
+Descriptive and brief headings are crucial to the quality of the
+documentation. Sphinx uses the headings within the
+:abbr:`ReST (RestructuredText)` files to generate the navigation of the HTML
+output and the outlines of the PDF files. The |CLOSIA| publishes the
+documentation as HTML making consistent heading levels extremely important.
+
+In addition to the title of the file, only three levels of headings are
+accepted. The following example shows all accepted levels of headings:
+
+.. code-block:: rst
+
+   Title
+   #####
+
+   Level 1 sections
+   ****************
+
+   Level 2 sections
+   ================
+
+   Level 3 sections
+   ----------------
+
+Headings must be written in sentence case. Learn more about the correct
+capitalization in our :ref:`grammar guide<grammar>`.
@@ -0,0 +1,188 @@
+/** @file
+ @brief Hello World Demo
+
+ A Hello World demo for the Nanokernel and the Microkernel.
+ */
+
+/*
+ * Copyright (c) 2012-2014 Wind River Systems, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** CONFIG_MICROKERNEL
+ The microkernel hello world demo has two tasks that use semaphores
+ and sleeps to take turns printing a greeting message at a
+ controlled rate.*/
+
+/** #else || CONFIG_NANOKERNEL
+ * The nanokernel hello world demo has a task and a fiber that use
+ * semaphores and timers to take turns printing a greeting message at
+ * a controlled rate.
+ */
+
+/**
+ * @def SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
+ * @brief Compute equivalence in ticks.
+ */
+/**
+ * @def SLEEPTIME
+ * @brief Specify delay between greetings (in ms).
+ */
+
+#if defined(CONFIG_STDOUT_CONSOLE)
+#include <stdio.h>
+#define PRINT           printf
+#else
+#include <misc/printk.h>
+#define PRINT           printk
+#endif
+
+#ifdef CONFIG_MICROKERNEL
+
+#include <zephyr.h>
+
+#define SLEEPTIME  500
+#define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
+
+/**
+ * @brief A loop saying hello.
+ *
+ * @details
+ * Actions:
+ * 	 -# Ouputs "Hello World!".
+ * 	 -# Waits, then lets another task run.
+
+ @param taskname The task's identification string.
+ @param mySem    The task's semaphore.
+ @param otherSem The other task's semaphore.
+ */
+void helloLoop(const char *taskname, ksem_t mySem, ksem_t otherSem)
+{
+	while (1)
+	{
+		task_sem_take (mySem, TICKS_UNLIMITED);
+
+		PRINT ("%s: Hello World!\n", taskname); /* Action 1 */
+
+		task_sleep (SLEEPTICKS); /* Action 2 */
+		task_sem_give (otherSem);
+	}
+}
+
+/**
+ * @brief Exchanges Hello messages with taskB.
+ *
+ * @details
+ * Actions:
+ *  -# taskA gives its own semaphore, thus it says hello right away.
+ *  -# Calls function helloLoop, thus taskA exchanges hello messages with taskB.
+ */
+void taskA(void)
+{
+	task_sem_give (TASKASEM); /* Action 1 */
+
+	helloLoop (__FUNCTION__, TASKASEM, TASKBSEM); /* Action 2 */
+}
+
+/**
+ * @brief Exchanges Hello messages with taskA.
+ *
+ * Actions:
+ *  -# Calls function helloLoop, thus taskB exchanges hello messages with taskA.
+ */
+void taskB(void)
+{
+	helloLoop (__FUNCTION__, TASKBSEM, TASKASEM); /* Action 1 */
+}
+
+#else
+
+#include <nanokernel.h>
+#include <nanokernel/cpu.h>
+
+#define SLEEPTIME  500
+#define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
+
+#define STACKSIZE 2000
+
+/** Declares a stack for a fiber with a size of 2000.*/
+char fiberStack[STACKSIZE];
+
+/** Declares a nanokernel semaphore for a task. */
+struct nano_sem nanoSemTask;
+
+/** Declares a nanokernel semaphore for a fiber.*/
+struct nano_sem nanoSemFiber;
+
+/**
+ * @brief Defines the turns taken by the tasks in the fiber.
+ *
+ * Actions:
+ * -# Initializes semaphore.
+ * -# Initializes timer.
+ * -# Waits for task, then runs.
+ * -# Outputs "Hello World!".
+ * -# Waits, then yields to another task.
+ */
+void fiberEntry(void) {
+	struct nano_timer timer;
+	uint32_t data[2] = { 0, 0 };
+
+	nano_sem_init(&nanoSemFiber); /* Action 1 */
+
+	nano_timer_init(&timer, data); /* Action 2 */
+
+	while (1) {
+
+		nano_fiber_sem_take(&nanoSemFiber, TICKS_UNLIMITED); /* Action 3 */
+
+		PRINT("%s: Hello World!\n", __FUNCTION__); /* Action 4 */
+
+		nano_fiber_timer_start(&timer, SLEEPTICKS); /* Action 5 */
+		nano_fiber_timer_test(&timer, TICKS_UNLIMITED);
+		nano_fiber_sem_give(&nanoSemTask);
+	}
+}
+
+/**
+ * @brief Implements the Hello demo.
+ *
+ * Actions:
+ * -# Outputs "hello".
+ * -# Waits, then signals fiber's semaphore.
+ * -# Waits on fiber to yield.
+ */
+void main(void) {
+	struct nano_timer timer;
+	uint32_t data[2] = { 0, 0 };
+
+	task_fiber_start(&fiberStack[0], STACKSIZE, (nano_fiber_entry_t) fiberEntry,
+			0, 0, 7, 0);
+
+	nano_sem_init(&nanoSemTask);
+	nano_timer_init(&timer, data);
+
+	while (1) {
+
+		PRINT("%s: Hello World!\n", __FUNCTION__); /* Action 1 */
+
+		nano_task_timer_start(&timer, SLEEPTICKS); /* Action 2 */
+		nano_task_timer_test(&timer, TICKS_UNLIMITED);
+		nano_task_sem_give(&nanoSemFiber);
+
+		nano_task_sem_take(&nanoSemTask, TICKS_UNLIMITED); /* Action 3 */
+	}
+}
+
+#endif
@@ -0,0 +1,88 @@
+.. _images:
+
+Images
+######
+
+Images or figures grab the reader's attention and convey information that
+sometimes is difficult to explain using words alone. Well-planned graphics
+reduce the amount of text required to explain information. Non-native English
+readers rely heavily on graphics because graphics enhance their understanding of the text.
+
+Follow these guidelines when creating graphics for the |CLOSIA|:
+
+* Save the image files in a :file:`figures` folder. The folder must be found
+  at the same level as the file containing the text.
+
+* Use only lower case letters for image filenames.
+
+* Separate multiple words in filenames using dashes.
+
+* Name figures with the filename of the file they appear on and add a number
+  to indicate their place in the file. For example: The third figure added to
+  the :file:`fibers.rst` file must be named :file:`fibers-3.png`.
+
+* Include a caption describing the figure's content and to use as a reference.
+  All figures must have a caption.
+
+* Use cross-references. Refer to your graphics in the main text flow.
+  Create a label using the filename of the image. Use the `:ref:` role to place
+  the cross reference, see :ref:`cross` for more details.
+
+* Place the figure immediately after its reference in the text flow or as
+  close as possible.
+
+* Keep figures simple. They should only contain the information the
+  reader needs.
+
+* Use figures judiciously. Don't use superfluous graphics and don't
+  use graphics as mere decorations. They must have purpose. You don't
+  need to show a screenshot of every single step or window in a software
+  installation procedure, for example.
+
+* Avoid volatility. Don't incorporate information into a graphic that
+  might change with each release, for example: product versions or
+  codename abbreviations.
+
+* Use only approved image formats. Use either PNG or JPEG bitmap files for
+  screenshots and SVG files for vector graphics. If a figure is not a
+  photograph or screenshot, please provide figure as a vector graphic to
+  ensure it can be changed later on.
+
+
+Examples
+********
+
+These examples follow the guidelines and can be used as a reference.
+
+The fiber context is represented in the diagram either as a box
+containing different objects or a :ref:`symbol <fibers-1.svg>`.
+
+.. _fibers-1.svg:
+
+.. figure:: figures/fibers-1.svg
+   :scale: 75 %
+   :alt: Fibers Execution Context Symbol
+
+   The graphic representation of the fibers execution context.
+
+   This symbol is used to illustrate the actions performed by the
+   abstract fibers execution context.
+
+Templates
+*********
+
+Use this template to add a figure to your documentation according to
+these guidelines.
+
+.. code-block:: rst
+
+   .. _file-name-#.ext:
+
+   .. figure:: figures/file-name-#.ext
+      :scale: 75%
+      :alt: Alternative text.
+
+      Figure 1: Brief caption detailing the contents of the image.
+
+      Any additional explanation, description or actions depicted in the
+      image. It can encompass multiple lines.
@@ -0,0 +1,117 @@
+.. _inline:
+
+Inline Markup
+*************
+
+Sphinx supports a large number of inline markup elements called roles. The
+|CLOSIA| documentation encourages the use of as many roles as
+possible. Thus, you can use any additional roles supported by Sphinx
+even if not listed here. Please refer to the `Sphinx Inline Markup`_
+documentation for the full list of supported roles.
+
+The following markup is required in every instance unless otherwise
+specified. Each item provides examples and a template for the correct use of
+the roles.
+
+* Use the `:abbr:` abbreviation role to define an acronym or an initialism.
+  Add the abbreviation markup only once per file. After the abbreviation, the
+  acronym can be used without further definition or markup. Do not use
+  abbreviation markup on headings.
+
+   :abbr:`API (Application Program Interface)`
+
+   Template:
+
+   ``:abbr:`TIA (This Is an Abbreviation)```
+
+* Use the `:command:` role when the name of a specific command is used in a
+  paragraph for emphasis. Use the ``.. code-block::`` directive for fully
+  actionable commands in a series of steps.
+
+   :command:`make`
+
+   Template:
+
+   ``:command:`command```
+
+* Use the `:option:` role to emphasize the name of a command option
+  with or without its value. This markup is usually employed in
+  combination with the `:command:` role. For example:
+
+   :option:`-f`
+   :option:`--all`
+   :option:`-o output.xsl`
+   The :command:`pandoc` command can be used without the :option:`-o`
+   option, creating an output file with the same name as the source
+   but a different extension.
+
+   Template:
+
+   ``:option:`Option```
+
+* Use the `:file:` role to emphasize a filename or directory. Do not use the
+  role inside a code-block but use it inside all notices that contain files
+  or directories. Place variable parts of the path or filename in brackets
+  `{}`.
+
+   :file:`collaboration.rst` :file:`doc/{user}/collaboration/figures`
+
+   Template:
+
+   ``:file:`filename.ext` :file:`path/or/directory```
+
+* Use the `:guilabel:` role to emphasize elements of a graphic
+  user interface within a description. It replaces the use of quotes
+  when referring to windows' names, button labels, options, or single
+  menu elements. Always follow the marked element with the appropriate
+  noun. For example:
+
+   In the :guilabel:`Tools` menu.
+   Press the :guilabel:`OK` button.
+   In the :guilabel:`Settings` window you find the :guilabel:`Hide
+   Content` option.
+
+   Template:
+
+   ``:guilabel:`UI-Label```
+
+* Use the `:menuselection:` role to indicate the navigation through a menu
+  ending with a selection. Every `:menuselection:` element can have up to two
+  menu steps before the selected item. If more than two steps are required,
+  it can be combined with a `:guilabel:` or with another `:menuselection:`
+  element. For example:
+
+   :menuselection:`File --> Save As --> PDF`
+   Go to :guilabel:`File` and select :menuselection:`Import --> Data
+   Base --> MySQL`.
+   Go to :menuselection:`Window --> View` and select :menuselection:`
+   Perspective --> Other --> C++`
+
+   Template:
+
+   ``:menuselection:`1stMenu --> 2ndMenu --> Selection```
+
+* Use the `:makevar:` role to emphasize the name of a Makefile variable.
+  The role can include only the name of the variable or the variable
+  plus its value.
+
+   :makevar:`PLATFORM_CONFIG`
+   :makevar:`PLATFORM_CONFIG=basic_atom`
+
+   Template:
+
+   ``:makevar:`VARIABLE```
+
+* Use the `:envvar:` role to emphasize the name of environment
+  variables. Just as with `:makevar:`, the markup can include only the
+  name of the variable or the variable plus its value.
+
+   :envvar:`ZEPHYR_BASE`
+   :envvar:`QEMU_BIN_PATH=/usr/local/bin`
+
+   Template:
+
+   ``:envvar:`ENVIRONMENT_VARIABLE```
+
+.. _Sphinx Inline Markup:
+   http://sphinx-doc.org/markup/inline.html#inline-markup
@@ -0,0 +1,25 @@
+.. _language:
+
+Language reference guide
+########################
+
+This section provides you with the accepted use of the English language. It
+includes information about words use, punctuation, and grammar. This guide
+does not replace a professional writer's review but is intended to help
+collaborators submit consistent contributions.
+
+To make translations easier and to make the content accessible to non-native
+speakers, |CLOSIA| uses Simple English. However, we have not implemented any
+controlled language standards.
+
+.. toctree::
+   :maxdepth: 2
+
+   simple
+   grammar
+   punctuation
+
+
+
+
+
@@ -0,0 +1,112 @@
+.. _lists:
+
+Lists
+#####
+
+We use two types of lists: numbered lists and bulleted lists. Use a
+numbered, or ordered, list when the order or priority of the items is
+important. Use a bulleted, or unordered, list when the order of the
+items is not important.
+
+For both kinds of list, strive to keep all items in the list parallel.
+See :ref:`parallelism`. Use a sentence style, making all the list items
+sentences.
+
+Numbered Lists
+**************
+Numbered (ordered) lists are most frequently used for procedures. Use
+numbered lists to show sequence for the items. Here are some guidelines
+for numbered lists:
+
+* Make sure the list is sequential in nature and not simply a
+  collection of items.
+* Introduce a numbered list with a sentence setup text. End the setup
+  fragment or sentence with a colon. Example: To configure the unit, do
+  the following:
+* Each item in the list should be parallel.
+* Without exception, treat numbered list items as full sentences and
+  end each list entry with a period, a colon, or a comma - when the entries
+  are complete sentences or a mixture of fragments and sentences. In
+  cases where the entries are short imperative sentences introducing
+  commands or code, end them with colons.
+* You may interrupt numbered lists with other paragraph styles, if the
+  interruption is some explanatory text, commands, or code.
+* Second-level steps are acceptable; avoid third-level steps.
+* Avoid single-step procedures; the minimum number of steps in a
+  procedure is two.
+* Do not create numbered lists that emulate flowcharts. The reader
+  should be able to execute the list of steps from first to last
+  without branching or looping.
+* Avoid over-using numbered lists, except in procedural documents such as
+  tutorial and step-by-step guides.
+* Use the `#` symbol for all list items. Use a three-space indentation for
+  second-level items and for the explanatory text, commands, or code. Example:
+
+#. Open the door.
+
+#. Enter the room.
+
+   The room you enter may be dark. If it is not equipped with a motion
+   sensor that triggers a light, you might want to turn on a light to
+   avoid tripping over furniture.
+
+#. Make a call.
+
+   #. Pick up the receiver.
+
+   #. Dial a number.
+
+   #. Talk to the other party or leave a message.
+
+   #. Hang up.
+
+#. Turn off the light.
+
+#. Leave the room.
+
+Bulleted Lists
+**************
+Use bulleted, or unordered, lists to reduce wordiness and paragraph
+density, particularly when a sequence is not required. Here are some
+guidelines for bulleted lists:
+
+* Introduce a bulleted list with a sentence. End the setup text with a
+  colon. Example: To repair the unit, you will need the following:
+* Each item in the list should complete the setup sentence staying
+  parallel.
+* Avoid interrupting bulleted lists with other paragraph styles.
+* Second-level bullets are acceptable; avoid third-level bullets.
+
+Use sentence style bullet lists.
+
+Sentence style bullet lists are punctuated like sentences because all
+items in the list are sentences. End all bullets with a period or a
+colon if the bullet introduces a second level list. For example:
+
+**Incorrect**
+
+When setting the user code remember:
+
+* make the user code easy to remember. Use a number that has a meaning
+  for you
+* change the code once a month
+* do not disclose the user code to anyone else. This includes the
+  security company
+
+**Correct**
+
+When setting the user code, it is important to remember a few things:
+
+* Use a number that has a meaning for you.
+* Change the code once a month.
+* Do not disclose the user code to anyone else. This includes the security
+  company.
+
+Fragment style bullet lists and presentation style bullet lists are not
+acceptable for either in-code documentation or stand alone
+documentation. They can only be used for presentations.
+
+Presentation style bullets have little or no punctuation. They are
+typically short phrases or even single words. They often start with a
+capital and end with no punctuation, unless they are full sentences.
+Use only for presentations.
@@ -0,0 +1,73 @@
+.. _notices:
+
+Notices: notes, cautions, warnings, and dangers
+###############################################
+
+We use four special types of notices: notes, cautions, warnings, and
+dangers. Here are some specific rules and tips with regard to these
+notices:
+
+* Do not use a notice directly after a heading. Notices must follow a
+  variant of body text.
+* Avoid back-to-back notices.
+* To improve readability, rewrite content to eliminate multiple
+  notices in a single module.
+* If there is no clean way to avoid using back-to-back notices, use a
+  different style or multiple paragraphs, for example, combine two
+  notes into one or separate them with body text.
+
+Notes
+*****
+
+Use notes sparingly. Avoid having more than one note per subsection. If
+you exceed this number consistently, consider rewriting the notes as
+main body text. Example:
+
+.. note::
+   A note is supposed to provide supplemental information, not
+   emphasized information.
+
+
+
+Cautions, Warnings, and Dangers
+*******************************
+
+Tell readers what will happen if they do not heed cautions or warnings,
+circuits will fry, electrical shock may kill you, etc.
+
+* Use "Caution" to identify hazards resulting in property damage
+  accidents, including data loss. Also use "Caution" to alert against
+  unsafe practices.
+* Use "Warning" and "Danger" for property damage accidents only if
+  personal injury risk appropriate to these levels is also involved.
+
+These are examples of typical notices, the correct syntax and the
+conditions for their usage:
+
+.. note::
+   Notes are ancillary bits of information, subordinate to the main
+   flow. Reserve the note tag for information that does not readily
+   flow with the main text but which you want to set apart for one
+   reason or another. Notes should be relatively short. If there is
+   more than enough information to warrant a short paragraph,
+   consider rewriting the note as body text.
+
+.. caution::
+   Cautions are low-level hazard messages that alert the user of
+   possible equipment, product, and software damage, including loss
+   of data. Cautions typically appear as a yellow triangle with a
+   black exclamation point.
+
+.. warning::
+   Warnings are mid-level hazards (more serious than cautions) that
+   are likely to cause product damage as well as bodily injury to
+   humans. Warnings may appear in a black triangle with orange hazard-
+   specific graphics for warnings (or with the colors reversed). The
+   most common warning is for electrical hazards, but there are many
+   other hazard-specific graphics.
+
+.. danger::
+   Dangers are high-level hazards that are likely to cause product
+   damage as well as bodily injury and even death to humans. Dangers
+   use a red triangle with white (and black) hazard-specific
+   graphics, the same as found on warnings.
@@ -0,0 +1,32 @@
+.. _parallelism:
+
+Parallelism
+###########
+
+Parallelism refers to the practice of using similar patterns of grammar, and
+sometimes length, to coordinate words, phrases, and clauses.
+
+Parallel construction is especially important in bulleted lists. The table
+shows some unparallel structures and how they can be made parallel with a
+little rewording.
+
+----------------------------------+----------------------------------+
+| Parallel (do)                    | Unparallel (don't)               |
+==================================+==================================+
+| 1. Mount the panel.              | 1. Mount the panel.              |
+| 2. Install the battery.          | 2. Battery installation.         |
+| 3. Wire the keypad.              | 3. Wiring the keypad.            |
+----------------------------------+----------------------------------+
+| The system sends a message to    | The system sent a message to the |
+| the call center, which calls the | call center, which calls the     |
+| customer and tells about the     | customer and will tell about the |
+| burglary.                        | burglary.                        |
+----------------------------------+----------------------------------+
+| The system tried to send alarm   | The system tried to send alarm   |
+| messages that were precise and   | messages that had precision and  |
+| accurate.                        | were accurate.                   |
+----------------------------------+----------------------------------+
+| You need to install the panel,   | You need to install the panel,   |
+| wire the sensors, and test the   | wire the sensors, and you        |
+| phone line.                      | must test the phone line.        |
+----------------------------------+----------------------------------+
@@ -0,0 +1,86 @@
+.. _punctuation:
+
+Punctuation guide
+#################
+
+This section contains all the information regarding the correct use of
+punctuation for the |CLOSIA| documentation.
+
+Commas, Semicolons, and Colons
+******************************
+Here are the most common problems encountered with commas, semicolons,
+and colons. Please refer to Merriam-Webster's Collegiate Dictionary
+when in doubt.
+
+Serial Commas
+=============
+
+When writing a series of items, use the serial comma before the
+coordinating conjunctions *and* and *or* to avoid confusion and ambiguity.
+For example:
+
+* Mom, Dad, and I are going to the game.
+* Mom, Dad and I are going to the game.
+
+The first example uses the serial comma. It is clear in this sentence
+that three people are going to the game. The second example does NOT
+have a comma preceding the and. The reader may interpret this as
+meaning the same thing as the first sentence, namely that three people
+are going to the game, or that the speaker is addressing "Mom" and
+telling her that only two people are going to the game.
+
+Commas in Numbers
+=================
+
+Use commas to divide large numbers into sets of three digits. Use
+periods for decimal points. Do not divide decimal digits into sets of
+three.
+
+Do not use a comma to separate four-digit bit/byte numbers.
+
+Do not use a comma to separate four-digit page numbers.
+
+Do not use a comma or other punctuation to separate decimals.
+
+
+Semicolons ";"
+==============
+
+Here are some rules governing the use of semicolons:
+
+* Use semicolons in long, sentence-style bulleted phrase lists.
+
+* Use semicolons when two equal clauses are joined because of
+  similarity of construction or meaning.
+
+* Use semicolons in a series of items when at least one of the items
+  itself includes a comma.
+
+Examples of semicolon usage:
+
+Similar construction: The prewidget comes before the widget; the
+postwidget comes after it.
+
+Comma-inclusive series: We traveled through Casper, Wyoming; Boise,
+Idaho; and Eugene, Oregon.
+
+Colons ":"
+==========
+
+If the text following a colon is a sentence, capitalize the
+first word after the colon. If the subsequent text is not a sentence,
+do not capitalize the first term unless it is a title. For example:
+
+* This is a capitalization example: Donuts do not cause holes.
+
+* These is a noncapitalization example: colons, semicolons, and commas.
+
+* In a title, use title case following the colon. Example: Tires: How
+  to Fix a Flat.
+
+* Use a colon at the end of a sentence or phrase that introduces
+  examples, a list, a path, user input, or code.
+
+* Don't use a colon to introduce graphics, tables, or sections.
+
+* Don't use a colon at the end of a task title or any heading.
@@ -0,0 +1,42 @@
+.. _rest:
+
+RestructuredText guide
+######################
+
+The |CLOSIA| uses Sphinx and RestructuredText as authoring tools for its
+documentation. This section contains the preferred methods for using the
+:abbr:`ReST (RestructuredText)` markup on your documents. Please refer to the
+`Sphinx documentation`_ for the complete list of available markup and use
+as much markup as possible.
+
+Remember: **Changing incorrect markup is easier than adding markup from
+scratch.**
+
+We provide templates, examples, and use scenarios to help you write and edit
+documents easily. Use only the templates provided to ensure your content is
+consistent with the rest of the documentation.
+
+Contributions with incorrect use of markup will not be merged until the
+markup is fixed. If you have any questions regarding markup, send an email to
+our mailing list at dev@lists.clearlinux.org and we will gladly help.
+
+To allow for easy copy and paste of the provided templates,
+they are provided using either the "\`\`" parenthesis, for single line
+templates, or the code-block directive, for multi-lined templates.
+
+Every use case is explained, examples provided and, lastly,
+templates supplied.
+
+.. toctree::
+   :maxdepth: 3
+
+   headings
+   inline
+   tables
+   cross
+   images
+   code
+
+
+.. _Sphinx documentation:
+   http://sphinx-doc.org/contents.html
@@ -0,0 +1,305 @@
+.. _simple:
+
+Simple English
+##############
+
+Simple English is a generic term for communication that emphasizes
+clarity, brevity, and avoiding unnecessarily complicated or
+technical terms. It encourages writers to create content that is clear
+and appropriate to the audience's reading skills and knowledge.
+
+Simple English improves the clarity of procedural technical writing,
+makes translation easier, and improves comprehension for people whose
+first language is not English.
+
+|CLOSIA| does not use controlled language, which restricts the writer's
+vocabulary to a list of approved words. Some preferences are evidently in
+place.
+
+Short sentences and paragraphs
+******************************
+
+Clear writing should average 15 to 20 words per sentence. This does not
+mean every sentence should be the same length. Vary your writing by
+mixing short sentences with longer ones, but stick to the basic
+principle of one main idea in a sentence, plus one additional point if
+needed.
+
+Similarly, restrict your paragraph length to about six sentences.
+Remember the basic structure of a paragraph: Introduction, body and
+conclusion. Both the introduction and the conclusion should be one
+sentence long. The body of a paragraph should never exceed four
+sentences. Here less is more.
+
+Simple words
+************
+
+Choosing simple words increases reader comprehension and reduces
+ambiguity. Here are some guidelines on making good simple word choices:
+
+* Avoid jargon. Jargon is a type of language that is only understood
+  by a particular group of people, such as an industry or a club. You
+  can use jargon when writing for an audience who will understand, but
+  avoid over using it, especially on the general public.
+* Be consistent. Use one term for each concept or action and use it
+  consistently. Don't use a different term for the same object or
+  action when you refer to it subsequently.
+* Keep your style plain but avoid dullness. Avoid clichés, idioms, and
+  metaphors. Many of these devices are not easily understood across
+  different cultures and can lead to confusion.
+* Avoid "fancy" words and phrases. The goal is to get the information
+  across, not to impress the reader with your vocabulary, so avoid
+  bureaucratic, flowery or literary style. Here are some examples of
+  "formal" words to avoid and preferred "informal" alternatives in
+  parentheses:
+
+*  commence (start, begin)
+*  consequently (so)
+*  in excess of (more than)
+*  in the event of (if)
+*  prior to (before)
+*  should you wish (if you want)
+*  utilize (use)
+*  instance (example)
+
+Strong verbs
+************
+The stronger and clearer you can make your verbs, the more directly you
+communicate information to your audience.
+
+Keep these basic guidelines in mind as you check your verbs:
+
+* Use imperatives.
+* Use active voice not passive voice.
+* Avoid linking verbs; is, seems, becomes.
+* Convert weak verbs and nominalizations to strong verbs.
+* Be concise.
+* Avoid "there are" and "it is" constructions.
+
+.. note::
+  The examples in the following sections offer two versions of the same
+  information. The incorrect version always comes first and is formatted *in
+  italics*. The correct version always comes second and is formatted **in
+  bold**.
+
+Imperatives
+===========
+
+Commands, officially called imperatives, are the fastest and most direct
+way of giving someone instructions. Imperatives are an extension of the
+second-person pronoun you. The word you is implied.
+
+Be concise.
+
+Example:
+
+*I would appreciate it if you would send it to me.*
+
+**Send it to me.**
+
+
+Present Tense vs. Future Tense
+==============================
+
+Use simple present tense instead of future tense for most text. Future
+tense is acceptable for conditional statements, for example in a
+caution or a warning.
+
+*The system will operate at a nominal temperature of 180 degrees Fahrenheit.*
+
+**The system operates at a nominal temperature of 180 degrees Fahrenheit.**
+
+Action Verbs vs. Nominalizations
+================================
+
+Avoid nominalizations, which are nouns formed from verbs. For example:
+
+===================== =====================
+Verbs 						Nominalizations
+===================== =====================
+complete  						completion
+introduce  						introduction
+provide  						provision
+fail  							failure
+arrange  						arrangement
+install  						installation
+===================== =====================
+
+The problem with nominalizations is that they are often used instead of
+the verbs they come from. Because they are merely the names of things,
+they sound as if nothing is actually happening in the sentence. Like
+passive verbs, too many of them make writing very dull and heavy-going.
+
+Here are some examples.
+
+*We had a discussion about the matter.*
+
+**We discussed the matter.**
+
+*The blizzard will cause a stoppage of the trains.*
+
+**The blizzard will stop the trains.**
+
+*IT has completed the installation of the software.*
+
+**IT has installed the software.**
+
+Infinitives vs. Participles
+===========================
+
+* Avoid present participial forms and gerunds, words ending in -ing,
+  unless they are part of a technical name.
+* Use infinitives instead of participials in this type of
+  construction. For example:
+
+*There is no way of verifying this.*
+
+**There is no way to verify this.**
+
+
+Active Voice vs. Passive Voice
+==============================
+Use active voice whenever possible to show clearly who or what is
+performing an action.
+
+* Active voice follows standard English word order:
+  SUBJECT–VERB–OBJECT (optional). Modifiers come before or immediately
+  following the terms they modify.
+* Passive voice reverses the order and weakens the verb: OBJECT–be
+  VERB–by SUBJECT (optional).
+* Writing sentences in the passive voice, we often have to use the
+  verb to be and sometimes the preposition "by".
+
+Examples:
+
+
+*A mistake was made.* (By whom?)
+
+**I made a mistake.**
+
+*The sheriff was shot by me.*
+
+**I shot the sheriff.**
+
+*Version 2.0 was released in June.*
+
+**We released version 2.0 in June.**
+
+.. note::
+   Sometimes it is okay to use passive voice. For example, you may
+   use passive voice to avoid gender-specific pronouns, to avoid
+   blaming someone, or to address situations where the subject, who
+   did the action, is unknown or irrelevant.
+
+Noun phrases
+************
+Avoid long strings of nouns. Even native English speakers might have
+difficulty determining which term modifies one or another in long
+strings.
+
+Similarly, avoid long noun phrases with multiple adjectives. Try to
+limit the number of modifiers in any noun phrase to two terms maximum.
+
+Often the best way to split up these long noun strings is to separate
+them into digestible prepositional phrases. This tends to lengthen them
+but makes them much easier to understand.
+
+Examples of some long noun phrases and possible rewording:
+
+*Power management mechanism integration policies*
+
+**Integration policies for power management mechanisms**
+
+*Signal integrity test deck requirements*
+
+**Requirements for test desks that measure signal integrity**
+
+*Building radon source location method*
+
+**Method for locating the source of radon in buildings**
+
+*Employee compensation level evaluation procedures*
+
+**Procedures for evaluating an employee's compensation level**
+
+Pronouns
+********
+
+First Person
+============
+
+We recommend using we or |CL|, if you want to sound more formal, to provide
+an agent, someone who does the action in a sentence, and avoid passive
+constructions such as "It is recommended...." For example:
+
+
+*5 MB is recommended.*
+
+**We recommend 5 MB.**
+
+*It is recommend that you set the value as low as possible.*
+
+**We recommend setting the value as low as possible.**
+
+*This setting has not been validated.*
+
+**Intel has not validated this setting.**
+
+Second Person
+=============
+
+Write directly to the reader and use the second-person pronoun "you"
+rather than "the user". For example:
+
+*If the widget is to be compressed....*
+
+**If you want to compress the widget...**
+
+*If reduced costs are wanted...*
+
+*If the user wants to reduce costs...*
+
+**If you want to reduce costs...**
+
+
+Third Person
+============
+
+Third person pronouns tend to create subject-verb agreement errors
+because writers often introduce a gender-neutral third person plural
+they. Rewrite these sentences using a third person plural antecedent.
+Avoid third person singular pronouns, especially the gender-specific
+pronouns he and she, and, if necessary, rewrite these sentences using
+plurals to avoid a gender-specific references in gender-indeterminate
+situations.
+
+The preferred hierarchy of third-person pronoun usage is:
+
+*Wrong*
+
+*If a user needs to update their account...*
+
+Do not use the third person plural for a singular subject.
+
+*Avoid*
+
+*If a user forgets her password...*
+
+Do not force the feminine pronoun set (she) unless there is a specific,
+approved feminine antecedent or there is some other very strong,
+circumstantial reason to do so.
+
+Acceptable
+
+If a user needs to update his account...
+
+In traditional English usage, it is acceptable to use the masculine
+pronoun set (he) when the gender is neutral or indeterminate.
+This is often the rule in romance languages and other languages.
+
+**Preferred**
+
+**If users need to update their accounts...**
+
+Often the best solution is to use the plural form to avoid pronoun
+problems.
@@ -0,0 +1,29 @@
+.. _steps:
+
+Step-by-step instructions
+#########################
+
+* Provide a sequence of numbered steps, see :ref:`lists`. Do not provide a
+  paragraph of sentences.
+
+* Describe one action per step.
+
+* If the user needs to do the same thing for several procedures, refer to
+  earlier steps rather than repeating them.
+
+* When steps and diagrams flow down a page side-by-side, put text on the left
+  and diagrams on the right.
+
+* When steps include commands or code blocks, put the commands or code blocks
+  after the step that includes them.
+
+* If directions can appear in only one place, either text or figure, put them
+  in the text; don't hide directions in diagrams.
+
+* When a series of steps is supported by one figure, refer to the figure in
+  the introductory text: "See Figure 15 and do the following:"
+
+* When a series of steps is supported by two or more figures, avoid referring
+  to a range of figures. Rather, refer to a specific figure in the relevant
+  step and show the figure immediately after the reference. **Do not write**:
+  "See figures 15 through 22 and do the following:"
@@ -0,0 +1,17 @@
+.. _structures:
+
+Consistent content structures guide
+###################################
+
+This section guides you through the different content structures used in the
+|CLOSIA| documentation. This section serves as an example of the correct use
+of markup. Refer to our :ref:`rest` to learn more about using
+restructuredText to author your content.
+
+.. toctree::
+   :maxdepth: 2
+
+   lists
+   steps
+   notices
+   parallelism
@@ -0,0 +1,106 @@
+.. _tables:
+
+Tables
+######
+
+Tables must only be used for information that is either too numerous or too
+related for a list to be appropriate. The smallest acceptable table is 2x2
+not counting the table header. The |CLOSIA| uses special ReStructuredText
+markup to make including tables easier. If you plan on adding a table
+consider transforming it into a list before you embark on creating a table.
+Follow these general guidelines:
+
+* Use tables sparingly.
+
+* Stick to the 72-78 characters line length limit.
+
+* Indent the contents correctly. This allows the content to be read even if
+  it is not rendered.
+
+* Only create a table if the body of the table is larger than 6, that means
+  at least 2x3 or 3x2.
+
+ReST supports several types of tables. |CL| uses grid and
+:abbr:`CSV-tables (Comma Separated Values tables)`. Grid tables are only
+suited for very short content since they must be fully drawn. CSV-tables
+support multi-lined cells, are easy to update and allow more layout
+options.
+
+Use grid tables for small tables where the layout needs to be determined
+manually. For example:
+
+-----------------+------------------------+--------------+------------+
+| Name            | Purpose                | Known        | References |
+| (or brand name) |                        | Applications |            |
+=================+========================+==============+============+
+| Super Glue      | Glues things together  | Small car    | Quick Fix, |
+|                 | with extra strength.   | repairs.     |  2010.     |
+-----------------+------------------------+--------------+------------+
+| Masking Tape    | Stops paint from       | Painting     | Master     |
+|                 | covering a surface     | walls.       | Painter,   |
+|                 | allowing for sharp     |              | 2007.      |
+|                 | edges.                 |              |            |
+-----------------+------------------------+--------------+------------+
+
+Use '=' between the table heading and the rows to define the table header. Do
+not add emphasis to the contents of the table header using \*\*.
+
+
+This template can help you create grid tables:
+
+.. code-block:: rst
+
+   +------------------------+------------+----------+----------+
+   | Header row, column 1   | Header 2   | Header 3 | Header 4 |
+   | (header rows optional) |            |          |          |
+   +========================+============+==========+==========+
+   | body row 1, column 1   | column 2   | column 3 | column 4 |
+   +------------------------+------------+----------+----------+
+   | body row 2             | ...        | ...      |          |
+   +------------------------+------------+----------+----------+
+
+CSV-tables are more flexible than grid tables. They can be updated easily and
+support several layout options. For example:
+
+.. csv-table:: Frozen Delights!
+   :header: "Treat", "Quantity", "Description"
+   :widths: 15, 10, 30
+
+   "Albatross", 2.99, "On a stick!"
+   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
+   crunchy, now would it?"
+   "Gannet Ripple", 1.99, "On a stick!"
+
+CSV-tables can have a title, the header row is optional and separate from the
+rest of the table, each column's width is customizable among others. See the
+Sphinx `CSV-tables documentation`_ to learn all the possible options
+available.
+
+This template can help you create CSV-tables:
+
+.. code-block:: rst
+
+   .. csv-table:: Table title (optional)
+      :header: The header, values, for each column
+      :widths: 15, 10, 30
+
+      If the values, in the, "table go beyond the line length, use quotes to
+      keep the content together."
+      Numbers like, 10, are never surrounded by quotes.
+      Text can, "be", in quotes but it is only needed for longer lines.
+
+The template renders as:
+
+.. csv-table:: Table title (optional)
+   :header: The header, values, for each column
+   :widths: 15, 10, 30
+
+   If the values, in the, "table go beyond the line length, use quotes to keep
+   the content together."
+   Numbers like, 10, are never surrounded by quotes.
+   Text can, "be", in quotes but it is only needed for longer lines.
+
+
+
+.. _CSV-tables documentation:
+   http://docutils.sourceforge.net/docs/ref/rst/directives.html#csv-table
@@ -5,6 +5,8 @@ Clear Linux\* OS on Microsoft\* Azure\*

 Clear Linux OS is now an offering in the Azure Marketplace.

+:ref:`fig-wp-install-1`
+
 Clear Linux OS is designed with cloud and data center environments in mind
 and is tuned to maximize the performance and value of Intel® architecture.
 In Azure our boot times are lightning-quick, with all on-boot services
@@ -105,6 +105,8 @@ go to: http://<your_website>/blog/wp-admin/install.php.

 Your screen should look like figure 1:

+.. _fig-wp-install-1:
+
 .. figure:: figures/wp-install-1.png
    :alt: WordPress language selection
    :width:     600
@@ -112,7 +114,9 @@ Your screen should look like figure 1:
    WordPress language selection screen.

 Select :guilabel:`English` for the language and click the
-:guilabel:`Continue` button.
+:guilabel:`Continue` button. :ref:`As shown on figure 1<fig-wp-install-1>`
+
+

 The WordPress installation continues until the welcome screen shown in figure
 2 appears: