Merge "Update How To Guide & Git submodules"

1 files changed, 75 insertions, 75 deletions

diff --git a/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst b/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst
index 380b05cce..6bce35df9 100644
--- a/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst
+++ b/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst
@@ -1,65 +1,46 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 
 
-Documentation Guide
-===================
-
-This page describes how documentation is created for the Open Network Automation Platform (ONAP).
-ONAP projects create a variety of document types depending on the nature of the project.
-Some projects will create detailed technical descriptions such as configuration parameters or how to
-use or extend the functionality of platform component.
-These descriptions may be together as a reference for that project and/or
-be used in documents tailored to a specific user audience and task they are performing.
-
-Acknowledgement
----------------
-
-Much of the content in this document is derived from similar documentation processes used in other Linux Foundation Projects
-including OPNFV and Open Daylight.
-
-.. contents::
-   :depth: 3
-   :local:
-
-Getting Started
+Introduction
+============
+This guide describes how to create documentation for the Open Network
+Automation Platform (ONAP).  ONAP projects create a variety of document
+types depending on the nature of the project. Some projects will create
+detailed technical descriptions such as configuration parameters or how
+to use or extend the functionality of platform component.
+These descriptions may be used together as a reference for that project
+and/or be used in documents tailored to a specific user audience and
+task they are performing.
+
+Much of the content in this document is derived from similar 
+documentation processes used in other Linux Foundation 
+Projects including OPNFV and Open Daylight.
+
+
+End to End View
 ---------------
-ONAP documentation is stored in git repositories, changes are managed with gerrit reviews, and published documents
-automatically generated when there is a change in any source used to build the documentation.
-
-Authors create source for documents in reStructured Text (RST) that is automatically rendered to HTML and PDF
-and published on Readthedocs.io.
-The developer Wiki can reference these rendered documents directly allowing projects to
-easily maintain current release documentation.
-Read :ref:`this page <include-documentation>` which describes how documentation is created from
-ONAP Documentation project (doc) documentation source and other ONAP projects providing source material.
-
-Licencing Your Documentation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-All contributions to the ONAP project are done in accordance with the ONAP licensing requirements.
-Documentation in ONAP is contributed
-in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license.
-All documentation files need to be licensed using the text below. The license may be applied in the first lines of
-all contributed RST files:
-
-.. code-block:: bash
-
- .. This work is licensed under a Creative Commons Attribution 4.0 International License.
- .. (c) <optionally add copywriters name>
+ONAP documentation is stored in git repositories, changes are managed
+with gerrit reviews, and published documents generated when there is a
+change in any source used to build the documentation.
 
- These lines will not be rendered in the html and pdf files.
+Authors create source for documents in reStructured Text (RST) that is
+rendered to HTML and PDF and published on Readthedocs.io.
+The developer Wiki or other web sites can reference these rendered 
+documents directly allowing projects to easily maintain current release
+documentation.
 
-Storing Content Files in Your Repository
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-All documentation for your project should be structured and stored in `<your_project_repo>/docs/` directory.
-The documentation tool chain will look in these directories when triggered by verify and merge events.
 
-.. index:: master, document
+Structure
+---------
+A top level master_document structure is used to organize all 
+documents for an ONAP release that reside in the doc git repository. 
+Complete documents or guides may reside here and reference parts of 
+source for documentation from other project repositories 
+A starting structure is shown below and may change as content is
+intergrated for each release.   Others ONAP projects will provide
+content that is referenced from this structure.
 
-Document Structure and Contribution
------------------------------------
-A top level master_document structure is proposed for organizing all documents
-in the four areas as shown below with additional detail under each area.
-This structure may change as we gain experience with the first release of ONAP.
+.. index:: master
 
 
 ::
@@ -88,29 +69,48 @@ This structure may change as we gain experience with the first release of ONAP.
             ├── guidelines
             └── sdk
 
+
+
+Source Files
+------------
+All documentation for a project should be structured and stored 
+in or below `<your_project_repo>/docs/` directory as Restructured Text.
+ONAP jenkins jobs that verify and merge documentation are triggered by
+file changes in the docs directory and below.
+
+
+.. index:: licensing
+
+Licencing
+---------
+All contributions to the ONAP project are done in accordance with the
+ONAP licensing requirements.   Documentation in ONAP is contributed
+in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license.
+All documentation files need to be licensed using the text below. 
+The license may be applied in the first lines of all contributed RST 
+files:
+
+.. code-block:: bash
+
+ .. This work is licensed under a Creative Commons Attribution 4.0 International License.
+ .. (c) <optionally add copyrights company name>
+
+ These lines will not be rendered in the html and pdf files.
+
+
+
 Templates
-^^^^^^^^^
-Where multiple sections with similar content are expected, templates can be created and stored 
-under `doc/docs/templates/` and used a starting point for similar content.
-For example the high level architecture and interface information for an ONAP component.
-A template is a directory name in `doc/docs/templates` , the directory contains at least an
-index.rst file with a starting point for creating content, and as needed
-references to other sources in the template directory.  Current templates are shown below.
+---------
+To encourage consistency of information across components, some
+templates are available as a starting point under `doc/docs/templates/`
+and listed below.  With the "show source" feature on html pages, you
+may be able to use portions of an existing page as starting point for
+creating new content.
+
 
 .. toctree::
    :maxdepth: 1
-   
-   ../../../templates/index
-
-Project teams are encouraged to reuse and propose new templates for reuse.
-
-Release Documentation
-^^^^^^^^^^^^^^^^^^^^^
-Release documentation is the set of documents that are published for each ONAP release.
-The documents have a master index.rst file in the <doc> repository and reference content as needed
-from other project repository.
-To provide content for these other projects place <content>.rst files in a directory
-in your repository that
-matches the master document and add a reference to that file in the correct place in the
-corresponding master index.rst. 
+   :glob:
 
+   ../../../templates/**/index
+