Differences

This shows you the differences between two versions of the page.

--- documentation:userguide [2016/01/05 12:21]
Christopher Price
+++ documentation:userguide [2016/02/09 12:24] (current)
Ryota Mibu [Document structure]
@@ Line 20: / Line 20: @@
 | Introduction to installation and configuration:  |''opnfvdocs/docs/userguide/introduction.rst''|
-The document is further compiled of project specific chapters, feature configuration descriptions, and validation procedures.  Every project providing features into the platform must provide a description in this document on how to use the features.
+The document is further compiled of project specific chapters, feature descriptions, and usage procedures.  Every project providing features into the platform should provide a description in this document on how to use the features.  The composite description content should be at a level that a user might understand how to use the features and capabilities and may also provide references to the projects own documentation for more detailed descriptions.
-All project specific files to be compiled into the user guide must be stored in your projects userguide folder.
+Project document content references are provided in the area staging files, there are three main sections to the user guide where you might provide content, the staging files are:
-| User Guide directory:             |''<repo>/docs/userguide/''|
+| Common OPNFV component level user guides:  | ''/opnfvdocs/docs/userguide/general-system.rst''|
-| Feature user guide:               |''<repo>/docs/userguide/featureusage.rst''|
+| OPNFV test project user guides:            | ''/opnfvdocs/docs/userguide/test-usage.rst''    |
-| Feature validation procedures:    |''<repo>/docs/userguide/validation.rst''|
+| OPNFV Feature user guides:                 | ''/opnfvdocs/docs/userguide/feature-usage.rst'' |
-==== Including your Documentation ====
+The project specific files to be compiled into the user guide must be stored in your projects userguide folder.
-Add your documentation to your repository in the folder structure and according to the templates listed above.  The documentation templates you will require are available in the opnfvdocs repository, you should copy the relevant templates to the /docs/userguide directory in your repository.  For instance if I wanted to document enabling my feature set in the platform I would follow an example like:
+| User Guide directory:             |''<repo>/docs/userguide/''| |
+| Testing user guide:         |''<repo>/docs/userguide/testusage.rst''|[[https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=docs/userguide/testusage.rst;hb=HEAD|template]]|
+| Feature user guide:                |''<repo>/docs/userguide/featureusage.rst''|[[https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=docs/userguide/featureusage.rst;hb=HEAD|template]]|
+==== Including your Documentation ====
+Add your documentation to your repository in the folder structure and according to the template listed above.  The documentation template you will require are available in the opnfvdocs repository, you should copy the relevant templates to the /docs/userguide directory in your repository.  For instance if I wanted to document enabling my feature set in the platform I would follow an example like:
   ' mkdir <my_repo>/docs/userguide '
   ' git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git '
-  ' cp opnfvdocs/docs/userguide/featureusage.rst <my_repo>/docs/userguide '
+  ' cp opnfvdocs/docs/userguide/userguide.rst <my_repo>/docs/userguide '
-  ' cp opnfvdocs/docs/userguide/validation.rst <my_repo>/docs/userguide '
+You should then add the relevant information to the template that will explain the usage of your feature and instructions for validating that the feature was used successfully //like checking the results of specific test cases//.  Be sure to maintain the creative commons license from the template and ensure all your documentation files include the license information.
-You should then add the relevant information to the template that will explain the usage of your feature and instructions for validating that the feature was used successfully //like checking the results of specific test cases//.
+Once your documentation is ready you should ensure they are compiled into the staging files by adding them to the master <section>.rst file in the opnfvdocs repository.  The staging files are structured in such a way that you should refer to your document in the correct section of the document structure.
+An example of how to add your documentation to the relevant sections of the feature-usage.rst file might be:
-Once your documentation is ready you should ensure they are compiled into the master file by adding them to the master index.rst file in the opnfvdocs repository.  The index.rst fils is structured in such a way that you should refer to your document in the correct section of the index.rst document structure.  The relevant sections for compiling project specific information are:
+  ' git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git '
+  ' cd opnfvdocs '
+  ' git review -s '
+  ' vim docs/userguide/feature-usage.rst '
-  * Feature Description - //for adding feature specific usage information//
+At this point you should add the references to your files into the index.rst file, for instance in the feature description section you would add the line:
-  * Validation Activities - //describing how to validate the usage was performed successfully//
-An example of how to add your documentation to the relevant sections of the index.rst file might be:
+  The following sections of the user guide provide feature specific usage guidelines and references.
+  Providing users the necessary information to leveraging the features in the platform,
+  some operation in this section may refer back to the guides in the general system usage section.
+  .. include:: ../projects/promise/userguide/userguide.rst
+  .. include:: ../projects/copper/userguide/userguide.rst  Using Brahmaputra Features
+  .. include:: ../projects/<my_repo>/userguide/userguide.rst''
+If this is the first contribution from your project to the composite document files you will need to add your project to the //build-composite.sh// file in the opnfvdocs directory.  This is done my editing the jsdgf file and adding your repository name to the //get_repo_names()// function of the script.  Assuming you are still in the opnfvdocs directory edit the file with the following command:
-  ' git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git '
+  ' vim build-composite.sh '
-  ' cd opnfvdocs '
-  ' git review -s '
-  ' vim docs/userguide/index.rst '
+Once you have the file open, add your projects repository to the //get_repo_names()// function:
-At this point you should add the references to your files into the index.rst file, for instance in the feature description section you would add ''../../<my_repo>/docs/userguide/featureusage.rst'' and in the Post Configuration Activities section you would add ''../../<my_repo>/docs/userguide/validation.rst''.  Once you have made these changes you need to push the patch back to the opnfvdocs team for review and integration.
+  get_repo_names() {
+    # NOTE: Not all repositories are ready for the composite docs,
+    #       so we have the repo name list here to add project docs
+    #       one by one. This will be replaced by the list in project.cfg .
+    # grep -v '^#' releng/jjb/opnfvdocs/project.cfg | sort
+    echo "sdnvpn"
+    echo "<my_repo>"
+Once you have made these changes you need to push the patch back to the opnfvdocs team for review and integration.
   ' git add . '

Wiki

User Tools

Site Tools

Differences

Page Tools