openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

On Tue, Oct 5, 2010 at 10:46 PM, Anne Gentle <anne@xxxxxxxxxxxxx> wrote:
> Hi all -
> I've been studying the existing web properties and want to provide some
> predictability in the documentation - what you can expect to find where. For
> tech docs, I see three potential locations.
>
> Sphinx (nova.openstack.org and swift.openstack.org)
> Wiki (wiki.openstack.org)
> Website (openstack.org)
>
> Based on the existing architecture, I would propose:
>
> Preserve swift.openstack.org and nova.openstack.org for developer
> documentation and conceptual information.
>  Point to the developer docs with links on the wiki but also write a lot of
> tutorials on the wiki.
> Set up community docs with constant updates on the wiki.
> Provide official docs with a release number assigned as releases revise on
> the openstack.org site.
>
> I'm thinking these assignments give us good, flexible options because we
> then cater to specific audiences - openstack.org site for
> bizdev/users/deployers, nova.openstack.org and swift.openstack.org for
> developers, and wiki.openstack.org for tutorials as well as pointers to
> other locations and project planning.

Perfect.  This sounds like a good plan to me.

I think the next thing to do is prioritize the documentation things
that need some TLC.

My list would be:

1) Install docs (still refers to things like Redis) for various platforms
2) Screenshots/screen output of what running various Nova commands
should look like on a normal system
3) Explanation of how the different parts of Nova work together from a
user perspective, not a developer's perspective
4) How to actually manage and run Nova. This page is just woeful:
http://wiki.openstack.org/UseNova20100729
5) Configurating Nova.  Nobody knows what the heck a "flagfile" is and
how to put one together.  There is little documentation on what the
various configuration options are.
6) Running the test suites on a local laptop and bzr branch properly

> I'd love your ideas and feedback on this approach - either write back on
> this thread or find me on IRC, or I can set up a call.
>
> I also have to say, now is the best time to write your way to understanding
> - we have fresh perspectives and a code freeze, an ideal combo. If you're
> not feeling particularly creative or you don't want to start with a fresh
> page, start with http://wiki.openstack.org/Documentation ; which offers an
> outline and links to pages.
>
> Last but not least, I've set up an OpenStack-doc group (link) so we can meet
> regularly to coordinate doc efforts. I need like-minded community doc peeps
> to bounce these ideas off of. :) Thanks to Nachi Ueno for joining - contact
> me off-list with your mailing address and I'll send you a t-shirt. Woo!

Nice :)

-jay