Jump to: navigation, search

Difference between revisions of "Documentation/Guidelines"

(Timing:When)
(Automation: Who)
 
(One intermediate revision by the same user not shown)
Line 12: Line 12:
  
 
Docs core does not always review content published to  
 
Docs core does not always review content published to  
docs.openstack.org/developer/<projectname>.  
+
* docs.openstack.org/developer/<projectname>.  
 +
 
 +
But they do review the index pages listing them:
 +
* docs.openstack.org/index.html
 +
* docs.openstack.org/developer/openstack-projects.html
 +
* docs.openstack.org/developer/language-bindings.html
  
 
Docs core members review:
 
Docs core members review:
docs.openstack.org/admin-guide-cloud/
+
* docs.openstack.org/admin-guide-cloud/
docs.openstack.org/openstack-ops/
+
* docs.openstack.org/openstack-ops/
docs.openstack.org/image-guide/
+
* docs.openstack.org/image-guide/
docs.openstack.org/cli-reference/
+
* docs.openstack.org/cli-reference/
docs.openstack.org/hot-reference/
+
* docs.openstack.org/hot-reference/
  
 
Specialty teams for docs are set up to review:
 
Specialty teams for docs are set up to review:
docs.openstack.org/security-guide/
+
* docs.openstack.org/security-guide/
docs.openstack.org/high-availability-guide/
+
* docs.openstack.org/high-availability-guide/
docs.openstack.org/networking-guide/
+
* docs.openstack.org/networking-guide/
docs.openstack.org/user-guide-admin/
+
* docs.openstack.org/user-guide-admin/
docs.openstack.org/user-guide/
+
* docs.openstack.org/user-guide/
docs.openstack.org/kilo/install-guide/**
+
* docs.openstack.org/kilo/install-guide/**
docs.openstack.org/kilo/config-reference/
+
* docs.openstack.org/kilo/config-reference/
  
 
== Writing: Who ==
 
== Writing: Who ==
Line 38: Line 43:
 
== Automation: Who ==
 
== Automation: Who ==
  
Currently Andreas manages to keep up with all our automation for builds, with
+
Currently Andreas manages to keep up most all our automation for builds, with
 
help from Christian Berendt, Anne Gentle and Gauvain Pocentek.
 
help from Christian Berendt, Anne Gentle and Gauvain Pocentek.
  

Latest revision as of 10:08, 17 June 2015

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

But they do review the index pages listing them:

  • docs.openstack.org/index.html
  • docs.openstack.org/developer/openstack-projects.html
  • docs.openstack.org/developer/language-bindings.html

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 most 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.