Merge "Updates to How To Create Documentation"

1 files changed, 87 insertions, 80 deletions

diff --git a/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst b/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst
index 9c5822d2b..276c51cf1 100644
--- a/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst
@@ -1,19 +1,20 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
 
 Introduction
 ============
 This guide describes how to create documentation for the Open Network
-Automation Platform (ONAP).  ONAP projects create a variety of 
-content depending on the nature of the project.  For example projects delivering
-a platform component may have different types of content than
+Automation Platform (ONAP).  ONAP projects create a variety of
+content depending on the nature of the project.  For example projects
+delivering a platform component may have different types of content than
 a project that creates libraries for a software development kit.
-The content from each project may be used together as a reference for that project
-and/or be used in documents are tailored to a specific user audience and
-task they are performing.
+The content from each project may be used together as a reference for
+that project and/or be used in documents are 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 
+Much of the content in this document is derived from similar
+documentation processes used in other Linux Foundation
 Projects including OPNFV and Open Daylight.
 
 
@@ -25,121 +26,126 @@ change in any source used to build the documentation.
 
 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 
+The developer Wiki or other web sites can reference these rendered
 documents directly allowing projects to easily maintain current release
 documentation.
 
 Why reStructuredText/Sphinx?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In the past, standard documentation methods included ad-hoc Word documents, PDFs, 
-poorly organized Wikis, and other, often closed, tools like Adobe FrameMaker.
-The rise of DevOps, Agile, and Continuous Integration, however, created a paradigm
-shift for those who care about documentation because:
+In the past, standard documentation methods included ad-hoc Word documents,
+PDFs, poorly organized Wikis, and other, often closed, tools like
+Adobe FrameMaker.  The rise of DevOps, Agile, and Continuous Integration,
+however, created a paradigm shift for those who care about documentation
+because:
 
-1. Documentation must be tightly coupled with code/product releases. In many cases,
-particularly with open-source products, many different versions of the same code
-can be installed in various production environments. DevOps personnel must have
-access to the correct version of documentation.
+1. Documentation must be tightly coupled with code/product releases.
+   In many cases, particularly with open-source products, many different
+   versions of the same code can be installed in various production
+   environments. DevOps personnel must have access to the correct version
+   of documentation.
 
 2. Resources are often tight, volunteers scarce. With a large software base
-like ONAP, a small team of technical writers, even if they are also developers,
-cannot keep up with a constantly changing, large code base. Therefore, those closest
-to the code should document it as best they can, and let professional writers edit for
-style, grammar, and consistency.
+   like ONAP, a small team of technical writers, even if they are also
+   developers, cannot keep up with a constantly changing, large code base.
+   Therefore, those closest to the code should document it as best they can,
+   and let professional writers edit for style, grammar, and consistency.
 
-Plain-text formatting syntaxes, such as reStructuredText, Markdown, and Textile,
-are a good choice for documentation because:
+Plain-text formatting syntaxes, such as reStructuredText, Markdown,
+and Textile, are a good choice for documentation because:
 
 a. They are editor agnostic
+
 b. The source is nearly as easy to read as the rendered text
+
 c. Documentation can be treated exactly as source code is (e.g. versioned,
-   diff'ed, associated with commit messages that can be included in rendered docs)
+   diff'ed, associated with commit messages that can be included
+   in rendered docs)
+
 d. Shallow learning curve
 
-The documentation team chose reStructuredText largely because of Sphinx, a Python-based
-documentation build system, which uses reStructuredText natively. In a code base
-as large as ONAP's, cross-referencing between component documentation was deemed
-critical. Sphinx and reStructuredText have built-in functionality that makes
-collating and cross-referencing component documentation easier.
+The documentation team chose reStructuredText largely because of Sphinx,
+a Python-based documentation build system, which uses reStructuredText
+natively. In a code base as large as ONAP's, cross-referencing between
+component documentation was deemed critical. Sphinx and reStructuredText
+have built-in functionality that makes collating and cross-referencing
+component documentation easier.
 
 Which docs should go where?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Frequently, developers ask where documentation should be created. Should they always use
-reStructuredText/Sphinx? Not necessarily. Is the wiki appropriate for anything at all? Yes.
+Frequently, developers ask where documentation should be created. Should
+they always use reStructuredText/Sphinx? Not necessarily. Is the wiki
+appropriate for anything at all? Yes.
 
 It's really up to the development team. Here is a simple rule:
 
-The more tightly coupled the documentation is to a particular version of the code,
-the more likely it is that it should be stored with the code in reStructuredText.
+The more tightly coupled the documentation is to a particular version
+of the code, the more likely it is that it should be stored with the
+code in reStructuredText.
 
-Two examples on opposite ends of the spectrum:
+The doc team encourages component teams to store as much documentation
+as reStructuredText as possible because:
 
-Example 1: API documentation is often stored literally as code in the form of formatted
-comment sections. This would be an ideal choice for reStructuredText stored in a doc repo.
+1. It is easier to edit component documentation for grammar,
+   spelling, clarity, and consistency.
 
-Example 2: A high-level document that describes in general how a particular component interacts
-with other ONAP components with charts. The wiki would be a better choice for this.
+2. A consistent formatting syntax across components will allow
+   flexibility in producing different kinds of output.
 
-The doc team encourages component teams to store as much documentation as reStructuredText
-as possible because:
+3. It is easier to re-organize the documentation.
 
-1. The doc team can more easily edit component documentation for grammar, spelling, clarity, and consistency.
-2. A consistent formatting syntax across components will allow the doc team more flexibility in producing different kinds of output.
-3. The doc team can easily re-organize the documentation.
-4. Wiki articles tend to grow stale over time as the people who write them change positions or projects.
+4. Wiki articles tend to grow in size and not maintained making it hard
+   to find current information.
 
 Structure
 ---------
-A top level master document structure is used to organize all 
-documents for an ONAP release and this resides in the gerrit doc 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
-integrated for each release.   Other ONAP projects will provide
-content that is referenced from this structure.
-
-
+A top level master document structure is used to organize all
+documents created by ONAP projects and this resides in the gerrit doc
+repository.  Complete documents or guides may reside here and
+reference parts of source for documentation from other project
+repositories.  Other ONAP projects will provide content that
+is referenced from this structure.
 
 ::
 
-        docs/
-        ├── releases
-        │   ├── major releases
-        │   ├── projects
-        │   ├── cryptographic signatures
-        │   └── references
-        ├── onap-developer
-        │   ├── architecture
-        │   ├── tutorials
-        │   ├── setting up
-        │   ├── developing
-        │   └── documenting
-        └── onap-users
-            ├── vf provider
-            ├── service designer
-            ├── service administrator
-            └── platform administrator
-
+    docs/
+    ├── guides
+    │   ├── onap-developer
+    │   │   ├── apiref
+    │   │   ├── architecture
+    │   │   ├── developing
+    │   │   ├── how-to-use-docs
+    │   │   ├── settingup
+    │   │   └── tutorials
+    │   └── onap-user
+    │       ├── onap-portal
+    │       ├── platform operations
+    │       ├── service design
+    │       ├── service deployment
+    │       ├── vnf provider
+    │       └── vnf certifier
+    ├── release
+    ├── templates
+    │   ├── collections
+    │   └── sections
+    └── use-cases
 
 
 Source Files
 ------------
-All documentation for a project should be structured and stored 
+All documentation for project repositories 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
 RST file changes in the top level docs directory and below.
 
-
-
 Licensing
 ---------
 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 
+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
@@ -150,6 +156,7 @@ files:
 
  These lines will not be rendered in the html and pdf files.
 
-When there are subsequent, significant contributions to a source file from a different contributor,
-a new copyright line may be appended after the last existing copyright line.
+When there are subsequent, significant contributions to a source file
+from a different contributor, a new copyright line may be appended
+after the last existing copyright line.