=============================
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