Content specification

Content specification

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. It is also good practice to contact the speciality team for the book you want to change to discuss your changes before starting work.

Use blueprints and specifications:

  • When adding large sections to an existing document to ensure involvement of the docs core 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.

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 Reporting documentation bugs.

Release-specific documentation

The Installation Tutorials and Guides, Configuration Reference, and Networking Guide are released at release time, with draft material published to https://docs.openstack.org/draft/draft-index.html. The rest of the guides are continuously released.

To patch for the release-specific documentation, you should generally patch to master branch with “backport: xxxx” (for example, backport: kilo) in the commit message.

For these guides, the docs.openstack.org site defaults to the current release, with the previous two releases being available under the More Releases & Languages drop-down. At release time, the documentation release team will update the default page to the new release, and remove the link to the oldest release. These docs are still available online for people who have direct URLs to the content, but they are no longer linked from the main site. For books written in DocBook XML, these old versions are clearly marked with the release name in red down the left-hand margin. We are currently developing a similar method of marking older books written in RST. The core team tracks usage of older versions, and as usage falls, can remove them entirely.

Installation Tutorials and Guides

The OpenStack Installation Tutorials and Guides describe a manual install process for multiple distributions based on the following packaging systems:

Document Source location Target location
Installation Tutorial for openSUSE and SUSE Linux Enterprise Server https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide https://docs.openstack.org/ocata/install-guide-obs/
Installation Tutorial for Red Hat Enterprise Linux and CentOS https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide https://docs.openstack.org/ocata/install-guide-rdo/
Installation Tutorial for Ubuntu 16.04 (LTS) https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide https://docs.openstack.org/ocata/install-guide-ubuntu/
Installation Tutorial For Debian With Debconf (is not provided for Ocata) https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide https://docs.openstack.org/newton/install-guide-debconf/
Installation Tutorial For Debian (is not provided for Ocata) https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide https://docs.openstack.org/newton/install-guide-debian/

Guides for deployers and administrators

Document Source location Target location
Configuration Reference https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/config-reference https://docs.openstack.org/ocata/config-reference/
OpenStack Networking Guide https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/networking-guide https://docs.openstack.org/ocata/networking-guide/

Continuously released documentation

These guides cover multiple versions and we follow the general release information. The guides cover the latest two versions, for example Juno and Kilo. The following exceptions apply:

  • Operations Guide: Icehouse target, revised specifically to target that release
  • HA Guide: Updated last at Havana timeframe, still needs updates

Guides for deployers and administrators

Document Source location Target location
OpenStack Architecture Design Guide https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/arch-design https://docs.openstack.org/arch-design/
OpenStack Administrator Guide https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/admin-guide https://docs.openstack.org/admin-guide/
OpenStack High Availability Guide https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/ha-guide https://docs.openstack.org/ha-guide/
OpenStack Security Guide https://git.openstack.org/cgit/openstack/security-doc/tree/security-guide https://docs.openstack.org/security-guide/
OpenStack Virtual Machine Image Guide https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/image-guide https://docs.openstack.org/image-guide/

Guides for end users

Document Source location Target location
OpenStack End User Guide https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/user-guide https://docs.openstack.org/user-guide/
OpenStack API Guide https://git.openstack.org/cgit/openstack/api-site/tree/api-quick-start https://developer.openstack.org/api-guide/quick-start/
OpenStack Command-Line Interface Reference https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/cli-reference https://docs.openstack.org/cli-reference/

API documentation

We are migrating away from WADL in 2016. Refer to OpenStack API documentation for details. Once the migration is complete, the API reference pages will be stored in the project repositories and we will have redirects in place for these API pages.

Project-specific guides

Each project maintains its own developer guide. They are published from each project repository. See https://docs.openstack.org/developer/openstack-projects.html and https://docs.openstack.org/developer/language-bindings.html.

Contributor guides

Generally, the https://docs.openstack.org/developer/ documentation is meant for contributors to OpenStack projects. Each project’s repo has a doc/source directory where RST source files are stored. They are built automatically with Sphinx when the patch is merged. For example, see https://git.openstack.org/cgit/openstack/horizon/tree/doc/source for the horizon contributor documentation source and https://docs.openstack.org/developer/horizon/ for the built documentation.

  • Infrastructure User Manual: Reference documentation for tools and processes used for all contributors to OpenStack projects. It includes instructions on how to create all the necessary accounts, setup development environment, use gerrit review workflow. The manual also covers more advanced topics, like how to create new git repositories. The manual is maintained by the OpenStack Infrastructure team.
Document Source location Target location
Documentation Contributor Guide https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/contributor-guide https://docs.openstack.org/contributor-guide/
Python Developer Documentation https://git.openstack.org/cgit/openstack/<project>/tree/master/doc/source/, such as https://git.openstack.org/cgit/openstack/nova/tree/doc/source https://docs.openstack.org/developer/openstack-projects.html
Language Bindings and Python Clients https://git.openstack.org/cgit/openstack/python-<project>client/tree/master/doc/source/, such as https://git.openstack.org/cgit/openstack/python-novaclient/tree/doc/source https://docs.openstack.org/developer/language-bindings.html
OpenStack Project Infrastructure https://git.openstack.org/cgit/openstack-infra/system-config/tree/doc/source https://docs.openstack.org/infra/system-config/
Tempest Testing Project https://git.openstack.org/cgit/openstack/tempest/tree/doc/source https://docs.openstack.org/developer/tempest/

Guides for contributors

Licenses

This section shows the license indicators as of March 20, 2015.

  • OpenStack Architecture Design Guide: Apache 2.0 and CC-by-sa 3.0
  • OpenStack Administrator Guide: Apache 2.0 and CC-by-sa 3.0
  • OpenStack Install Guides (all): Apache 2.0
  • OpenStack High Availability Guide: Apache 2.0
  • OpenStack Configuration Reference: Apache 2.0
  • OpenStack Networking Guide: Apache 2.0
  • OpenStack Security Guide: CC-by 3.0
  • Virtual Machine Image Guide: CC-by 3.0
  • OpenStack Operations Guide: CC-by 3.0
  • OpenStack End User Guide: CC-by 3.0
  • Command-Line Interface Reference: CC-by 3.0
  • Contributor dev docs (docs.openstack.org/developer/<projectname>): none indicated in output; Apache 2.0 in repo
  • OpenStack API Quick Start: none indicated in output; Apache 2.0 in repo
  • API Complete Reference: none indicated in output; Apache 2.0 in repo
  • Infrastructure User Manual: none indicated in output; CC-by 3.0 in repo

What to do to make more consistent output:

  • OpenStack Architecture Design Guide: Apache 2.0 and CC-by 3.0
  • OpenStack Administrator Guide: Apache 2.0 and CC-by 3.0
  • OpenStack Install Guides (all): Apache 2.0 and CC-by 3.0
  • OpenStack High Availability Guide: Apache 2.0 and CC-by 3.0
  • OpenStack Security Guide: CC-by 3.0
  • Virtual Machine Image Guide: CC-by 3.0
  • OpenStack Operations Guide: CC-by 3.0
  • OpenStack End User Guide: CC-by 3.0

These guides are created by “scraping” code:

  • OpenStack Configuration Reference: Apache 2.0 and CC-by 3.0
  • Command-Line Interface Reference: Apache 2.0 and CC-by 3.0

These guides have no indicator in output:

  • Contributor dev docs (docs.openstack.org/developer/<projectname>): none indicated in output; Apache 2.0 in repo
  • OpenStack API Quick Start: none indicated in output; Apache 2.0 in repo
  • API Complete Reference: none indicated in output; Apache 2.0 in repo

This guide has a review in place to get a license indicator in output:

  • Infrastructure User Manual: none indicated in output; CC-by 3.0 in repo
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.