Improve templates and add references in guides

[doc.git] / docs / guides / onap-developer / how-to-use-docs / include-documentation.rst

diff --git a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
index 789ad75..aa2def9 100644 (file)
--- a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
@@ -3,6 +3,7 @@
 
 Setting Up
 ==========
+
 Some initial set up is required to connect a project with
 the master document structure and enable automated publishing of
 changes as summarized in the following diagram and description below 
@@ -80,7 +81,7 @@ The following sequence will do this over ssh.
    git clone ssh://$lfid@gerrit.onap.org:29418/doc
    cd doc
    mkdir -p `dirname docs/submodules/$reponame`
-   git submodule add https://gerrit.onap.org/r/$reponame docs/submodules/$reponame.git
+   git submodule add ../$reponame docs/submodules/$reponame.git
    git submodule init docs/submodules/$reponame.git
    git submodule update docs/submodules/$reponame.git
 
@@ -130,11 +131,12 @@ to convert or add new content you can update the index and add files under the d
 The diagram below illustrates what is accomplished in the setup steps
 above from the perspective of a file structure created for a local test,
 a jenkins verify job, and/or published release documentation including:
-  - ONAP gerrit project repositories,
-  - doc project repository master document index.rst, templates, configuration, and other documents
-  - submodules directory where other project repositories and directories/files are referenced 
-  - file structure: directories (ellipses), files(boxes)
-  - references: directory/files (solid edges), git submodule (dotted edges), sphinx toctree (dashed edges)
+
+- ONAP gerrit project repositories,
+- doc project repository master document index.rst, templates, configuration, and other documents
+- submodules directory where other project repositories and directories/files are referenced 
+- file structure: directories (ellipses), files(boxes)
+- references: directory/files (solid edges), git submodule (dotted edges), sphinx toctree (dashed edges)
 
 
 .. graphviz::
@@ -200,19 +202,48 @@ Creating Restructured Text
 
 Templates and Examples
 ----------------------
-Some templates are available that capture the kinds of information
-useful for different types of projects and provide simple examples of 
-restructured text.
-You can: browse the templates below; show source to look at the Restructured
-Text and Sphinx directives used; and then copy the source either from a browser window
+Templates are available that capture the kinds of information
+useful for different types of projects and provide some examples of 
+restructured text.  We organize templates in the following way to: help authors 
+understand relationships between documents; keep the user audience context in mind when writing; 
+and tailor sections for different kinds of projects.
+
+**Sections** Represent a certain type of content.   A section is **provided** in a repository, to
+to describe something about the characteristics, use, capability, etc. of things in that repository.
+A section may also be **referenced** from other sections and in other repositories.
+The notes in the beginning of each section template provide
+additional detail about what is typically covered and where there may be references to the section.
+
+**Collections** Are a set of sections that are typically provided for a particular type
+of project, repository, guide, reference manual, etc.
+
+You can: browse the template *collections* and *sections* below; show source to look at the Restructured
+Text and Sphinx directives used; copy the source either from a browser window
 or by downloading the file in raw form from
-the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_.
+the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_ and
+then add them to your repository docs folder and index.rst.
+
+
+Sections
+++++++++
 
 .. toctree::
    :maxdepth: 1
    :glob:
 
-   ../../../templates/**/index
+   ../../../templates/sections/*
+
+
+Collections
++++++++++++
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   ../../../templates/collections/*
+
+
 
 In addition to these simple templates and examples 
 there are many open source projects (e.g. Open Daylight, Open Stack)
@@ -340,6 +371,7 @@ specified output folder directory.
 
 .. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content.
 
+.. _building-all-documentation:
 
 All Documentation
 -----------------