X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fguides%2Fonap-documentation%2Fintroduction.rst;fp=docs%2Fguides%2Fonap-developer%2Fhow-to-use-docs%2Fintroduction.rst;h=3bc00d9a3d10baa8f20bc5e328833c6d782b8259;hb=21d59414fca273aade30aa4209aca9bb35a5f78f;hp=242a2d23965d73233ed01de4da028e1070a8c2e0;hpb=830bc298c26764f3d98f3ca98adf7b3c1b3d0a3a;p=doc.git

diff --git a/docs/guides/onap-developer/how-to-use-docs/introduction.rst b/docs/guides/onap-documentation/introduction.rst
similarity index 57%
rename from docs/guides/onap-developer/how-to-use-docs/introduction.rst
rename to docs/guides/onap-documentation/introduction.rst
index 242a2d239..3bc00d9a3 100644
--- a/docs/guides/onap-developer/how-to-use-docs/introduction.rst
+++ b/docs/guides/onap-documentation/introduction.rst
@@ -1,12 +1,13 @@
 .. 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.
+.. Copyright 2022 ONAP
 
 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
+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
@@ -25,7 +26,7 @@ This includes all new features and changes to features that impact users.
 How do I create ONAP documentation?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ONAP documentation is written in ReStructuredText_ (an easy-to-read,
-what-you-see-is-what-you-get, plain text markup syntax).  The process for
+what-you-see-is-what-you-get, plain text markup syntax). The process for
 creating ONAP documentation and what documents are required are
 described in later sections of this Developer Documentation Guide.
 
@@ -36,7 +37,7 @@ 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,
+Adobe FrameMaker. The rise of DevOps, Agile, and Continuous Integration,
 however, created a paradigm shift for those who care about documentation
 because:
 
@@ -72,14 +73,29 @@ 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?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Which documents should go where?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A TSC Vote (2020, Feb. 19) approved the following usage policy:
 
-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.
+**DEVELOPER WIKI** is used for ONAP release, project, subcommitee and
+development related content, e.g.
 
-It's really up to the development team. Here is a simple rule:
+- project management (meetings, plans, milestones, members, ...)
+- project specific development guides
+- ongoing activities and discussions
+- ONAP community event documentation
+
+**READ THE DOCS** is used for all formal ONAP E2E and component documentation,
+e.g.
+
+- ONAP overview, architecture, API
+- ONAP developer guides (e.g. Documentation guide)
+- ONAP user guides (E2E)
+- ONAP component guides, release notes
+- ONAP administration/operations guides
+- ONAP use-case description and usage
+- ONAP tutorials
+- ONAP release notes
 
 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
@@ -99,88 +115,6 @@ as reStructuredText as possible because:
 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 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.
-
-.. code-block::
-
-   docs
-   ├── guides
-   │   ├── onap-developer
-   │   │   ├── apiref
-   │   │   ├── architecture
-   │   │   │   └── media
-   │   │   ├── developing
-   │   │   └── how-to-use-docs
-   |   |   |   ├── templates
-   │   |   |   |   ├── collections
-   │   |   |   |   └── sections
-   │   ├── onap-operator
-   │   │   ├── cloud_site
-   │   │   │   ├── aws
-   │   │   │   ├── azure
-   │   │   │   ├── k8s
-   │   │   │   ├── openstack
-   │   │   │   └── vmware
-   │   │   ├── onap-portal-admin
-   │   │   │   └── attachments
-   │   │   └── settingup
-   │   ├── onap-provider
-   │   ├── onap-user
-   │   │   ├── configure
-   │   │   │   ├── change_config
-   │   │   │   ├── pnf_connect
-   │   │   │   └── vnf_connect
-   │   │   ├── design
-   │   │   │   ├── control-loop
-   │   │   │   │   └── media
-   │   │   │   ├── media
-   │   │   │   ├── parameter_resolution
-   │   │   │   │   └── ubuntu_example
-   │   │   │   │       ├── cba-after-enrichment
-   │   │   │   │       │   ├── Definitions
-   │   │   │   │       │   ├── Templates
-   │   │   │   │       │   └── TOSCA-Metadata
-   │   │   │   │       ├── cba-before-enrichment
-   │   │   │   │       │   ├── Definitions
-   │   │   │   │       │   ├── Templates
-   │   │   │   │       │   └── TOSCA-Metadata
-   │   │   │   │       └── ubuntuCDS_heat
-   │   │   │   ├── pre-onboarding
-   │   │   │   │   └── media
-   │   │   │   ├── resource-onboarding
-   │   │   │   │   └── media
-   │   │   │   ├── service-design
-   │   │   │   │   └── media
-   │   │   │   ├── service-distribution
-   │   │   │   │   └── media
-   │   │   │   └── vfcreation
-   │   │   │       └── media
-   │   │   ├── instantiate
-   │   │   │   ├── instantiation
-   │   │   │   │   ├── nbi
-   │   │   │   │   ├── pnf_instance
-   │   │   │   │   ├── service_instance
-   │   │   │   │   ├── so1
-   │   │   │   │   ├── so2
-   │   │   │   │   ├── uui
-   │   │   │   │   ├── vid
-   │   │   │   │   ├── virtual_link_instance
-   │   │   │   │   └── vnf_instance
-   │   │   │   └── pre_instantiation
-   │   │   └── onap-portal-user
-   │   │       └── attachments
-   │   └── overview
-   │       └── media
-   └── release
-
-
 Source Files
 ------------
 All documentation for project repositories should be structured and stored