openstack-doc-core team mailing list archive

[Lorin Hochstein <lorin@xxxxxxxxxxxxxxxxxx>]

On Jul 27, 2012, at 3:04 PM, Anne Gentle <anne@xxxxxxxxxxxxx> wrote:

> Hi all -
> The various client projects are getting a consistency boost and I'm
> pretty excited about it. I'd like to know if anyone on the doc-core
> team is interested in working on client docs specifically. Here at
> Rackspace, Karin Levenstein is interested, but working on another
> project for a little while. I know that Dean Troyer was working on the
> consistency pieces for all the clients, and I've reached out to him as
> well.
> 
> So, my question is - on this team does anyone have a special interest
> in improving the client documentation? I'm talking about the
> command-line nova, glance, keystone, and swift commands and their
> parameters. How should we document those? Just on the command line
> itself? Is there a separate guide we should write for each? Would love
> your thoughts and if this is a special interest area for anyone,
> please let us all know your ideas.
> 

Anne:

I have some interest here, although not many cycles to work on it. :(

My own command-line documentation search workflow is:

1. Use the built-in "--help" or "help" command of the tool
2. Look at the man page
3. Go to the internet


If other people work like I do, then that's how I propose we prioritize the doc generation. I think we should also have a google'able web page for each tool. I suggest generating that content by writing the man page documentation in a format that can be easily transformed into HTML (we're already doing this, aren't we?) and just post the HTML-ized versions of the client man pages somewhere on docs.openstack.org. I don't think we need a separate guide for each.

Do we know if the python-openstackclient will be ready in time for the Folsom release (I guess this is a good question for Dean)?


Take care,

Lorin
--
Lorin Hochstein
Lead Architect - Cloud Services
Nimbis Services, Inc.
www.nimbisservices.com