documentation
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
documentation [2015/12/10 14:16] Ildiko Vancsa [How and where to store the document content files in your repository] |
documentation [2016/03/16 00:00] (current) Aric Gardner |
||
|---|---|---|---|
| Line 9: | Line 9: | ||
| 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 [[documentation:tools| documents toolchain instructions]] for more details on getting started in your project. | 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 [[documentation:tools| documents toolchain instructions]] for more details on getting started in your project. | ||
| The linked page above is written completely in generated artifacts, check the source to see how to do it yourself! | The linked page above is written completely in generated artifacts, check the source to see how to do it yourself! | ||
| + | |||
| + | ===== Licencing your documentation ===== | ||
| + | |||
| + | All contributions to the OPNFV project are done in accordance with the OPNFV licensing requirements. Documentation in OPNFV is contributed in accordance with the [[http://creativecommons.org/licenses/by/4.0|Creative Commons 4.0]] licence. | ||
| + | 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: | ||
| + | |||
| + | .. This work is licensed under a Creative Commons Attribution 4.0 International License. | ||
| + | .. http://creativecommons.org/licenses/by/4.0 | ||
| + | .. (c) <optionally add copywriters name> | ||
| + | |||
| + | These lines will not be rendered in the html and pdf files. | ||
| ===== How and where to store the document content files in your repository ===== | ===== How and where to store the document content files in your repository ===== | ||
| Line 18: | Line 29: | ||
| While many of your documents may be specific to your work there is a general structure proposed for storing and handling documents that are common across many projects. You are encouraged to establish the following basic structure for your project as needed: | While many of your documents may be specific to your work there is a general structure proposed for storing and handling documents that are common across many projects. You are encouraged to establish the following basic structure for your project as needed: | ||
| - | * Requirement Documentation: <repo>/docs/requirements/ | + | * Requirement Documentation: ''<repo>/docs/requirements/'' |
| - | * Should be where your requirement documentation is created | + | * Should be the folder for your requirement documentation |
| - | * Design Documentation: <repo>/docs/design/ | + | * Design Documentation: ''<repo>/docs/design/'' |
| - | * Should be where your upstream design documents (blueprints, development proposals, etc..) are stored | + | * Should be the folder for your upstream design documents (blueprints, development proposals, etc..) |
| - | * For details on requirements projects structures see the [[requirements_projects|Requirements Projects]] page | + | * For details on requirements projects' structures see the [[requirements_projects|Requirements Projects]] page |
| ==== Release documentation ==== | ==== Release documentation ==== | ||
| Line 31: | Line 42: | ||
| For release documents specific to a project, the documentation should be created in the projects' release directory. | For release documents specific to a project, the documentation should be created in the projects' release directory. | ||
| - | * Release Documentation: ''<repo>/docs/release/'' | + | * Release Documentation: ''<repo>/docs/release-notes/'' |
| * Should be the directory where any release specific documentation (release notes) is produced | * Should be the directory where any release specific documentation (release notes) is produced | ||
| Release documents that represent the OPNFV release as a whole have a specific structure and content collation method. 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 master //index.rst// file in ''<opnfvdocs>''. | Release documents that represent the OPNFV release as a whole have a specific structure and content collation method. 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 master //index.rst// file in ''<opnfvdocs>''. | ||
| - | * Platform Overview: ''<project dir>/docs/platformoverview'' | + | * Platform Overview: ''<repo>/docs/platformoverview'' |
| * Should be the folder for the overview of a release deliverable | * Should be the folder for the overview of a release deliverable | ||
| * Note this document will be compiled into OPNFVDOCS 'platformoverview' | * Note this document will be compiled into OPNFVDOCS 'platformoverview' | ||
| - | * Installation Manual: ''<project dir>/docs/configguide'' | + | * [[documentation:configguide|Installation and Configuration Guide]]: ''<repo>/docs/configguide'' |
| * Should be the folder for manuals to install/configure project specific components and features | * Should be the folder for manuals to install/configure project specific components and features | ||
| * Guides to validate project specific features can be included | * Guides to validate project specific features can be included | ||
| * Note this document will be compiled into OPNFVDOCS 'configguide' | * Note this document will be compiled into OPNFVDOCS 'configguide' | ||
| + | * NOTE: see [[documentation:configguide]]. | ||
| - | * User Guide: ''<project dir>/docs/userguide'' | + | * [[documentation:userguide|User Guide]]: ''<repo>/docs/userguide'' |
| * Should be the folder for manuals to use specific features | * Should be the folder for manuals to use specific features | ||
| * Can be the directory where API reference for project specific features are stored | * Can be the directory where API reference for project specific features are stored | ||
| * Can be the place for sotring typical scenario as an example | * Can be the place for sotring typical scenario as an example | ||
| * Note this document will be compiled into OPNFVDOCS 'userguide' | * Note this document will be compiled into OPNFVDOCS 'userguide' | ||
| - | |||
| ===== Documentation projects ===== | ===== Documentation projects ===== | ||
| [[documentation:opnfvdocs|OPNFV Documentation Project]] | [[documentation:opnfvdocs|OPNFV Documentation Project]] | ||
documentation.1449757008.txt.gz · Last modified: 2015/12/10 14:16 by Ildiko Vancsa
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: Creative Commons Attribution 4.0 International License
