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 3fc6f78ad2..b26ed51012 100644 --- a/doc/contributor-guide/source/index.rst +++ b/doc/contributor-guide/source/index.rst @@ -25,6 +25,7 @@ Contents writing-style.rst json_conventions.rst doc-bugs.rst + blueprints-and-specs.rst docs-review.rst tools_and_content_overview.rst cherry-pick.rst