docs/guides/onap-documentation/introduction.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0
   2 .. International License. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
   4 .. Copyright 2022 ONAP
   5
   6 Introduction
   7 ============
   8 This guide describes how to create documentation for the Open Network
   9 Automation Platform (ONAP). ONAP projects create a variety of
  10 content depending on the nature of the project. For example projects
  11 delivering a platform component may have different types of content than
  12 a project that creates libraries for a software development kit.
  13 The content from each project may be used together as a reference for
  14 that project and/or be used in documents that are tailored to a specific
  15 user audience and tasks they are performing.
  16
  17 Much of the content in this document is derived from similar
  18 documentation processes used in other Linux Foundation
  19 Projects including OPNFV and Open Daylight.
  20
  21 When is documentation required?
  22 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  23 All ONAP project contributions should have corresponding documentation.
  24 This includes all new features and changes to features that impact users.
  25
  26 How do I create ONAP documentation?
  27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28 ONAP documentation is written in ReStructuredText_ (an easy-to-read,
  29 what-you-see-is-what-you-get, plain text markup syntax). The process for
  30 creating ONAP documentation and what documents are required are
  31 described in later sections of this Developer Documentation Guide.
  32
  33 .. _ReStructuredText: http://docutils.sourceforge.net/rst.html
  34
  35 Why reStructuredText/Sphinx?
  36 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  37
  38 In the past, standard documentation methods included ad-hoc Word documents,
  39 PDFs, poorly organized Wikis, and other, often closed, tools like
  40 Adobe FrameMaker. The rise of DevOps, Agile, and Continuous Integration,
  41 however, created a paradigm shift for those who care about documentation
  42 because:
  43
  44 1. Documentation must be tightly coupled with code/product releases.
  45    In many cases, particularly with open-source products, many different
  46    versions of the same code can be installed in various production
  47    environments. DevOps personnel must have access to the correct version
  48    of documentation.
  49
  50 2. Resources are often tight, volunteers scarce. With a large software base
  51    like ONAP, a small team of technical writers, even if they are also
  52    developers, cannot keep up with a constantly changing, large code base.
  53    Therefore, those closest to the code should document it as best they can,
  54    and let professional writers edit for style, grammar, and consistency.
  55
  56 Plain-text formatting syntaxes, such as reStructuredText, Markdown,
  57 and Textile, are a good choice for documentation because:
  58
  59 a. They are editor agnostic
  60
  61 b. The source is nearly as easy to read as the rendered text
  62
  63 c. Documentation can be treated exactly as source code is (e.g. versioned,
  64    diff'ed, associated with commit messages that can be included
  65    in rendered docs)
  66
  67 d. Shallow learning curve
  68
  69 The documentation team chose reStructuredText largely because of Sphinx,
  70 a Python-based documentation build system, which uses reStructuredText
  71 natively. In a code base as large as ONAP's, cross-referencing between
  72 component documentation was deemed critical. Sphinx and reStructuredText
  73 have built-in functionality that makes collating and cross-referencing
  74 component documentation easier.
  75
  76 Which documents should go where?
  77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78 A TSC Vote (2020, Feb. 19) approved the following usage policy:
  79
  80 **DEVELOPER WIKI** is used for ONAP release, project, subcommitee and
  81 development related content, e.g.
  82
  83 - project management (meetings, plans, milestones, members, ...)
  84 - project specific development guides
  85 - ongoing activities and discussions
  86 - ONAP community event documentation
  87
  88 **READ THE DOCS** is used for all formal ONAP E2E and component documentation,
  89 e.g.
  90
  91 - ONAP overview, architecture, API
  92 - ONAP developer guides (e.g. Documentation guide)
  93 - ONAP user guides (E2E)
  94 - ONAP component guides, release notes
  95 - ONAP administration/operations guides
  96 - ONAP use-case description and usage
  97 - ONAP tutorials
  98 - ONAP release notes
  99
 100 The more tightly coupled the documentation is to a particular version
 101 of the code, the more likely it is that it should be stored with the
 102 code in reStructuredText.
 103
 104 The doc team encourages component teams to store as much documentation
 105 as reStructuredText as possible because:
 106
 107 1. It is easier to edit component documentation for grammar,
 108    spelling, clarity, and consistency.
 109
 110 2. A consistent formatting syntax across components will allow
 111    flexibility in producing different kinds of output.
 112
 113 3. It is easier to re-organize the documentation.
 114
 115 4. Wiki articles tend to grow in size and not maintained making it hard
 116    to find current information.
 117
 118 Source Files
 119 ------------
 120 All documentation for project repositories should be structured and stored
 121 in or below `<your_project_repo>/docs/` directory as Restructured Text.
 122 ONAP jenkins jobs that verify and merge documentation are triggered by
 123 RST file changes in the top level docs directory and below.
 124
 125 Licensing
 126 ---------
 127 All contributions to the ONAP project are done in accordance with the
 128 ONAP licensing requirements.   Documentation in ONAP is contributed
 129 in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license.
 130 All documentation files need to be licensed using the text below.
 131 The license may be applied in the first lines of all contributed RST
 132 files:
 133
 134 .. code-block:: bash
 135
 136  .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 137  .. http://creativecommons.org/licenses/by/4.0
 138  .. Copyright YEAR ONAP or COMPANY or INDIVIDUAL
 139
 140  These lines will not be rendered in the html and pdf files.
 141
 142 When there are subsequent, significant contributions to a source file
 143 from a different contributor, a new copyright line may be appended
 144 after the last existing copyright line.
 145
 146 Read The Docs URLs
 147 ------------------
 148
 149 When referencing versions of documentation a Read The Docs the following
 150 URL conventions should be used
 151
 152  +----------------------------------+----------------------------------------+
 153  | URL                              | To Refer to                            |
 154  +==================================+========================================+
 155  | docs.onap.org                    | Most recent approved named release     |
 156  +----------------------------------+----------------------------------------+
 157  | docs.onap.org/en/latest          | Latest master branch all projects      |
 158  +----------------------------------+----------------------------------------+
 159  | docs.onap.org/en/*named release* | An approved name release eg. amsterdam |
 160  +----------------------------------+----------------------------------------+