Hi all --<br><br>This release brings yet another web property to our
collection and so far it is a hit - <a href="http://docs.openstack.org/" target="_blank">docs.openstack.org</a>. 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. <br>
<br>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. <br><br>Here are
additional guidelines as well. <br>
<br>
<a href="http://wiki.openstack.org/" target="_blank">wiki.openstack.org</a>
(wikitext or RST) <br>-----------------------------------------------<div id=":2c7"><br>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 <a href="http://nova.openstack.org/" target="_blank">nova.openstack.org</a>,
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. <br>
<br><a href="http://nova.openstack.org/" target="_blank">nova.openstack.org</a>,
<a href="http://swift.openstack.org/" target="_blank">swift.openstack.org</a>,
<a href="http://glance.openstack.org/" target="_blank">glance.openstack.org</a>
(RST)<br>
---------------------------------------------------------------------------------------------<br>
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.<br>
<br><a href="http://docs.openstack.org/" target="_blank">docs.openstack.org</a>
(DocBook)<br>-----------------------------------------<br>The
source for this site is housed in a new project, <a href="http://launchpad.net/openstack-manuals" target="_blank">http://launchpad.net/openstack-manuals</a>.
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.<br>
<br>
- <span>doc</span>/source/docbkx contains the DocBook XML
source files and images<br>
- <span>doc</span>/build/docbook-xsl-1.76.1/webhelp
contains the <span>OpenStack</span><br><div>
transforms to create the HTML using an ant build<br>
- <span>doc</span>/buildpdf/rc-maven-cloud-docs
contains the <span>OpenStack</span> transforms and Maven mojo to create the PDFs<br>
- <span>doc</span>/staging/ contains the files that are
copied to <br>
<a href="http://docs.openstack.org/" target="_blank">docs.<span>openstack</span>.org</a><br><br>I
plan to create a <a href="http://docs.openstack.org/current" target="_blank">docs.openstack.org/current</a> to keep updated during
the entire release cycle. Which brings me to...<br>
</div><br>Versions of Doc<br>----------------------<br>For RST-based
documentation, you can get to a point-release of a docs site by going to
<a href="http://swift.openstack.org/1.1" target="_blank">http://swift.openstack.org/1.1</a>,
for example. We'll keep doing that for ongoing releases. <br>
<br>Wrap-up (Finally!)<br>-----------------------<br>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!<br>
<br>Anne</div><div style="margin: 2em 0pt;" name="sig_d4a6b6619e"><div style="padding: 5px; font-size: 11px; color: rgb(102, 102, 102); font-family: sans-serif;">
<strong>Anne Gentle</strong>
<br>
<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a><br>
<div style="font-size: 10px;">
<a href="http://justwriteclick.com/" target="_blank">my blog</a> |
<a href="http://xmlpress.net/publications/conversation-community/" target="_blank">my book</a> |
<a href="http://www.linkedin.com/in/annegentle" target="_blank"><span>LinkedIn</span></a> | <a href="http://del.icio.us/annegentle" target="_blank">Delicious</a> |
<a href="http://twitter.com/annegentle" target="_blank">Twitter</a>
</div></div></div>