From a6c3d1dbd3617f3a2e634aefb36a6fe1f3953067 Mon Sep 17 00:00:00 2001 From: Maria Zlatkova Date: Thu, 15 Oct 2015 19:36:19 +0300 Subject: [PATCH] [Contributor Guide] Blueprints and specifications Converts the Blueprints and specifications section of the HowTo wikipage: https://wiki.openstack.org/wiki/Documentation/HowTo#When_to_write_a_blueprint_description_in_docs-specs Change-Id: If2f4c80a69e67a94004125efc4ab77faf89ef695 Implements: blueprint docs-contributor-guide --- .../source/blueprints-and-specs.rst | 38 +++++++++++++++++++ doc/contributor-guide/source/index.rst | 1 + 2 files changed, 39 insertions(+) create mode 100644 doc/contributor-guide/source/blueprints-and-specs.rst diff --git a/doc/contributor-guide/source/blueprints-and-specs.rst b/doc/contributor-guide/source/blueprints-and-specs.rst new file mode 100644 index 0000000000..000aef928b --- /dev/null +++ b/doc/contributor-guide/source/blueprints-and-specs.rst @@ -0,0 +1,38 @@ +============================= +Blueprints and specifications +============================= + +The Documentation team uses specifications in the `docs-specs repository`_ to +maintain large changes. Approved specifications are published at +`Documentation Program Specifications`_. For tracking purposes, a blueprint is +created for each specification. + +Use blueprints and specifications: + +* When adding large sections to an existing document to ensure involvement of + the core doc team. +* When adding an entirely new deliverable to the docs project. +* For any work that requires both content and tooling changes, such as + addition of the API reference site. +* For any large reorganization of a deliverable or set of deliverables. +* For automation work that needs to be designed prior to proposing a patch. +* For work that should definitely be discussed at a summit. + +A specification needs two +2 votes from the docs-specs-core team. See the +current list of `docs-specs core team`_. For more information, see: +`Blueprints and specifications`_. + +Use bugs against openstack-manuals or openstack-api-site: + +* For known content issues, even if you have to do multiple patches to close + the bug. +* To add content that is just missing. +* For known errors in a document. + +For more information, see: :ref:`doc_bugs`. + +.. Links +.. _`docs-specs repository`: http://git.openstack.org/cgit/openstack/docs-specs/ +.. _`Documentation Program Specifications`: http://specs.openstack.org/openstack/docs-specs/ +.. _`docs-specs core team`: https://review.openstack.org/#/admin/groups/384,members +.. _`Blueprints and specifications`: https://wiki.openstack.org/wiki/Blueprints#Blueprints_and_Specs diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index 7a9562afef..77a767b212 100644 --- a/doc/contributor-guide/source/index.rst +++ b/doc/contributor-guide/source/index.rst @@ -24,6 +24,7 @@ Contents writing-style.rst json_conventions.rst doc-bugs.rst + blueprints-and-specs.rst docs-review.rst tools_and_content_overview.rst