openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi all --

This release brings yet another web property to our collection and so far it
is a hit - docs.openstack.org. I'm thrilled at how it has turned out, and am
indebted to all who helped. This site is the first step towards providing
admin docs in addition to developer docs. So if you're wondering, well,
where do I contribute doc now that there's a site explosion? Let me outline
the steps to take to find a good home for your documentation efforts.

First of all, you can always send me documentation - hard copy, papyrus,
emails, and I'll prioritize it's placement. I love working with all of you
and brainstorming where your content goes.

Here are additional guidelines as well.

wiki.openstack.org (wikitext or RST)
-----------------------------------------------

The OpenStack wiki contains draft documentation but should ideally contain
project docs, specs, doc drafts, and outlines. Any dev or user doc on the
wiki is subject to constant change so if there's a page you want to keep an
eye on (like Nova installations for example), add it to your Notifications
list (under User > Settings > Notifications in the wiki). I've also begun a
copy/paste effort to put RST in wiki pages to avoid multiple maintenance on
pages that are also housed on nova.openstack.org, for example. There are
great pages on the wiki that I want to take to the other doc sites, for
example the Nova deploy page on the wiki should be highlighted in other
locations as well.

nova.openstack.org, swift.openstack.org, glance.openstack.org (RST)
---------------------------------------------------------------------------------------------
The RST pages stored with the project code should be written with a
developer audience in mind, although many times you'll find there is overlap
in what an admin needs to know and what a developer needs to know. High
priorities for those sites are wider coverage of doc strings, API doc, i18N
methodology, and architecture concepts that'll help developers.

docs.openstack.org (DocBook)
-----------------------------------------
The source for this site is housed in a new project,
http://launchpad.net/openstack-manuals. It's not yet part of the build
process and is manually built right now. (I'll work with Monty and/or Soren
to automate builds, detailed email to them to follow.) You can build the
output if you want or just submit changes to the source XML.

 - doc/source/docbkx contains the DocBook XML source files and images
 - doc/build/docbook-xsl-1.76.1/webhelp contains the OpenStack
transforms to create the HTML using an ant build
 - doc/buildpdf/rc-maven-cloud-docs contains the OpenStack transforms and
Maven mojo to create the PDFs
 - doc/staging/ contains the files that are copied to
docs.openstack.org

I plan to create a docs.openstack.org/current to keep updated during the
entire release cycle. Which brings me to...

Versions of Doc
----------------------
For RST-based documentation, you can get to a point-release of a docs site
by going to http://swift.openstack.org/1.1, for example. We'll keep doing
that for ongoing releases.

Wrap-up (Finally!)
-----------------------
I want to keep encouraging doc contributions - thanks for all the work so
far, but please realize we need to fill in the holes. The flow of content
should be - write code, ensure it has doc strings, write RST in the
individual projects and devs, write DocBook for admins, and keep me in the
loop but don't rely on me solely. With these guidelines, let's rock the doc!

Anne
*Anne Gentle*
anne@xxxxxxxxxxxxx
 my blog <http://justwriteclick.com/> | my
book<http://xmlpress.net/publications/conversation-community/>|
LinkedIn <http://www.linkedin.com/in/annegentle> |
Delicious<http://del.icio.us/annegentle>|
Twitter <http://twitter.com/annegentle>