Jump to: navigation, search

Documentation/Guidelines

< Documentation
Revision as of 13:17, 13 June 2015 by Annegentle (talk | contribs) (Adds a documentation guidance page)

Timing:When

For current projects, continually update the documentation. Preferably there are doc patches for every blueprint or feature added.

For new projects, docs can go onto docs.openstack.org after a project gets approved by the TC and moved to the OpenStack git namespace.

Reviews: Who

The centralized doc team has to give approval to publish certain centralized guides that are related to multiple projects. Install Guides, configuration guides (high availability, security), API reference, admin guides, ops guides. All these types of guides are in that category.

Docs core does not always review content published to docs.openstack.org/developer/<projectname>.

Docs core members review: docs.openstack.org/admin-guide-cloud/ docs.openstack.org/openstack-ops/ docs.openstack.org/image-guide/ docs.openstack.org/cli-reference/ docs.openstack.org/hot-reference/

Specialty teams for docs are set up to review: docs.openstack.org/security-guide/ docs.openstack.org/high-availability-guide/ docs.openstack.org/networking-guide/ docs.openstack.org/user-guide-admin/ docs.openstack.org/user-guide/ docs.openstack.org/kilo/install-guide/** docs.openstack.org/kilo/config-reference/

Writing: Who

Projects should seek writers and developers who are willing to follow a set of conventions maintained by the docs team. Those conventions are available on the OpenStack wiki at Documentation/Conventions.

Automation: Who

Currently Andreas manages to keep up with all our automation for builds, with help from Christian Berendt, Anne Gentle and Gauvain Pocentek.

Content: What

If you ever question what to write, the docs team is happy to help. Typically we consider the audience (such as, cloud admins, operators, or application developers using an OpenStack cloud) and what tasks they want to complete (such as, configuring external networks or launching an instance).

Content: Where

Consult the Documentation/ContentSpecs page to determine where a document gets published. All of our docs are licensed with the intention of sharing with attribution, so you can take the doc content and repurpose it as long as you only use the OpenStack logo with brand guidelines in place. Refer to openstack.org/brand if you have questions.