From d917fdc2eb1a2c98a2503c9f024f3b3a27d8c286 Mon Sep 17 00:00:00 2001 From: ChristopherPrice Date: Wed, 10 Aug 2016 11:21:29 +0200 Subject: Creating a template for feature projects to produce userguide and scenario description documents This template will be pushed to features projects in Colorado to help them create the right documentation for the Colorado release. The documentation will be feature and scenario specific at a level where that makes sense while allowing common activities like instalation to be handled in documents for the installation tools. Change-Id: I649c583233ab8d8f8c3ebf7ddf8ae539dae15c8a Signed-off-by: ChristopherPrice --- .../scenarios/scenario.name/index.rst | 16 +++++++++++ .../scenario.name/scenario.description.rst | 32 ++++++++++++++++++++++ .../userguide/feature.userguide.rst | 19 +++++++++++++ docs/feature.templates/userguide/index.rst | 23 ++++++++++++++++ 4 files changed, 90 insertions(+) create mode 100644 docs/feature.templates/scenarios/scenario.name/index.rst create mode 100644 docs/feature.templates/scenarios/scenario.name/scenario.description.rst create mode 100644 docs/feature.templates/userguide/feature.userguide.rst create mode 100644 docs/feature.templates/userguide/index.rst (limited to 'docs') diff --git a/docs/feature.templates/scenarios/scenario.name/index.rst b/docs/feature.templates/scenarios/scenario.name/index.rst new file mode 100644 index 000000000..59ada34e9 --- /dev/null +++ b/docs/feature.templates/scenarios/scenario.name/index.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) + +=================================== + overview and description +=================================== +.. This document will be used to provide a description of the scenario for an end user. +.. You should explain the purpose of the scenario, the types of capabilities provided and +.. the unique components that make up the scenario including how they are used. + +.. toctree:: + :maxdepth: 3 + + ./scenario.description.rst + diff --git a/docs/feature.templates/scenarios/scenario.name/scenario.description.rst b/docs/feature.templates/scenarios/scenario.name/scenario.description.rst new file mode 100644 index 000000000..afd587915 --- /dev/null +++ b/docs/feature.templates/scenarios/scenario.name/scenario.description.rst @@ -0,0 +1,32 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) + +Introduction +============ +.. In this section explain the purpose of the scenario and the types of capabilities provided + +Scenario components and composition +=================================== +.. In this section describe the unique components that make up the scenario, +.. what each component provides and why it has been included in order +.. to communicate to the user the capabilities available in this scenario. + +Scenario usage overview +======================= +.. Provide a brief overview on how to use the scenario and the features available to the +.. user. This should be an "introduction" to the userguide document, and explicitly link to it, +.. where the specifics of the features are covered including examples and API's + +Limitations, Issues and Workarounds +=================================== +.. Explain scenario limitations here, this should be at a design level rather than discussing +.. faults or bugs. If the system design only provide some expected functionality then provide +.. some insight at this point. + +References +========== + +For more information on the OPNFV Colorado release, please visit +http://www.opnfv.org/colorado + diff --git a/docs/feature.templates/userguide/feature.userguide.rst b/docs/feature.templates/userguide/feature.userguide.rst new file mode 100644 index 000000000..b8adfa592 --- /dev/null +++ b/docs/feature.templates/userguide/feature.userguide.rst @@ -0,0 +1,19 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) + + description +===================== +.. Describe the specific features and how it is realised in the scenario in a brief manner +.. to ensure the user understand the context for the user guide instructions to follow. + + capabilities and usage +================================ +.. Describe the specific capabilities and usage for feature. +.. Provide enough information that a user will be able to operate the feature on a deployed scenario. + + +----------------------------------------------- +.. Describe with examples how to use specific features, provide API examples and details required to +.. operate the feature on the platform. + diff --git a/docs/feature.templates/userguide/index.rst b/docs/feature.templates/userguide/index.rst new file mode 100644 index 000000000..cc84670fc --- /dev/null +++ b/docs/feature.templates/userguide/index.rst @@ -0,0 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) + +==================== + user guide +==================== + +.. The feature user guide should provide an OPNFV user with enough information to +.. use the features provided by the feature project in the supported scenarios. +.. This guide should walk a user through the usage of the features once a scenario +.. has been deployed and is active according to the installation guide provided +.. by the installer project. + +.. toctree:: + :maxdepth: 3 + +.. The feature.userguide.rst file should contain the text for this document +.. additional documents can be added to this directory and added in the right order +.. to this file as a list below. + + ./feature.userguide.rst + -- cgit 1.2.3-korg