Documentation guide ported from wiki
[opnfvdocs.git] / docs / how-to-use-docs / documentation-guide.rst
1 =====================
2 Documentation Guide
3 =====================
4
5 This page intends to cover the documentation handling for OPNFV. OPNFV projects are expected to create a variety of document types, according to the nature of the project. Some of these are common to projects that develop/integrate features into the OPNFV platform, e.g. Installation Instructions and User/Configurations Guides. Other document types may be project-specific.
6
7 .. contents::
8    :depth: 3
9    :local:
10
11 Getting Started with Documentation for Your Project
12 ----------------------------------------------------
13 OPNFV documentation is automated and integrated into our git & gerrit toolchains.
14
15 We use RST document templates in our repositories and automatically render to HTML and PDF versions of the documents in our artifact store, our WiKi is also able to integrate these rendered documents directly allowing projects to use the revision controlled documentation process for project information, content and deliverables.
16 Read :ref:`this page <include-documentation>` which elaborates on how documentation is to be included within opnfvdocs.
17
18 Enabling the documentation toolchain in your project
19 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
20 There are some basic steps you will need to perform in order to get the toolchain working in your repository, this include setting up Jenkins jobs and establishing your project documentation structure. See the document toolchain instructions for more details on getting started in your project.
21 The linked page above is written completely in generated artifacts, check the source to see how to do it yourself!
22
23 Licencing your documentation
24 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
25 All contributions to the OPNFV project are done in accordance with the OPNFV licensing requirements. Documentation in OPNFV is contributed in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ licence.
26 All documentation files need to be licensed using the creative commons licence. The following example may be applied in the first lines of all contributed RST files:
27
28 .. code-block:: bash
29
30  .. This work is licensed under a Creative Commons Attribution 4.0 International License.
31  .. http://creativecommons.org/licenses/by/4.0
32  .. (c) <optionally add copywriters name>
33
34 These lines will not be rendered in the html and pdf files.
35
36 How and where to store the document content files in your repository
37 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
38 All documentation for your project should be structured and stored in the :code:`<repo>/docs/` directory. The documentation toolchain will look in these directories and be triggered on events in these directories when generating documents.
39
40 Document structure and contribution
41 -------------------------------------
42 A general structure is proposed for storing and handling documents that are common across many projects but also for documents that may be project specific. The documentation is divided into three areas Release, Development and Testing. Templates for these areas can be found under :code:`opnfvdocs/docs/templates/`.
43
44 Project teams are encouraged to use templates provided by the opnfvdocs project to ensure that there is consistency across the community. Following representation shows the expected structure:
45
46 ::
47
48         docs/
49         ├── developer
50         │   ├── design
51         │   ├── overview
52         │   └── requirements
53         ├── release
54         │   ├── configguide
55         │   ├── installation
56         │   ├── release-notes
57         │   ├── scenarios
58         │   │   └── scenario.name
59         │   └── userguide
60         └── testing
61
62
63 Release documentation
64 ^^^^^^^^^^^^^^^^^^^^^^^^
65 Release documentation is the set of documents that are published for each OPNFV release. These documents are created and developed following the OPNFV release process and milestones and should reflect the content of the OPNFV release.
66 These documents have a master index.rst file in the <opnfvdocs> repository and extract content from other repositories. To provide content into these documents place your <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 index.rst file in :code:`opnfvdocs/docs/release/`.
67
68 **Platform Overview**: :code:`opnfvdocs/docs/release/overview`
69
70 - Note this document is not a contribution driven document
71 - Content for this is prepared by the Marketing team together with the opnfvdocs team
72
73 **Installation Instruction**: :code:`<repo>/docs/release/installation`
74
75 - Folder for documents describing how to deploy each installer and scenario descriptions
76 - Release notes will be included here <To Confirm>
77 - Security related documents will be included here
78 - Note that this document will be compiled into 'OPNFV Installation Instruction'
79
80 **User Guide**: :code:`<repo>/docs/release/userguide`
81
82 - Folder for manuals to use specific features
83 - Folder for documents describing how to install/configure project specific components and features
84 - Can be the directory where API reference for project specific features are stored
85 - Note this document will be compiled into 'OPNFV userguide'
86
87 **Configuration Guide**: :code:`<repo>/docs/release/configguide`
88
89 - Brief introduction to configure OPNFV with its dependencies.
90
91 **Release Notes**: :code:`<repo>/docs/release/release-notes`
92
93 - Changes brought about in the release cycle.
94 - Include version details.
95
96 Testing documentation
97 ^^^^^^^^^^^^^^^^^^^^^^^^
98 *Structure TBD together with test projects*
99
100 Development Documentation
101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
102 Documentation not aimed for any specific release such as design documentation, project overview or requirement documentation can be stored under /docs/development. Links to generated documents will be dislayed under Development Documentaiton section on docs.opnfv.org. You are encouraged to establish the following basic structure for your project as needed:
103
104 **Requirement Documentation**: :code:`<repo>/docs/development/requirements/`
105
106 - Folder for your requirement documentation
107 - For details on requirements projects' structures see the `Requirements Projects <https://wiki.opnfv.org/display/PROJ/Requirements+Projects>`_ page.
108
109 **Design Documentation**: :code:`<repo>/docs/development/design`
110
111 - Folder for your upstream design documents (blueprints, development proposals, etc..)
112
113 **Project overview**: :code:`<repo>/docs/development/overview`
114
115 - Folder for any project specific documentation.
116