openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

Firstly, Anne, I think I can speak for any number of developers and
users of OpenStack in giving you a big THANK YOU for all the excellent
work you and others have done on the OpenStack documentation. I've
said it before, but professional software has professional
documentation, and you've pushed our documentation from haphazard at
best to organized and well on its way to being professional. Thank you
very much for your hard work, Anne.

I support the way you've been breaking down the various documentation
on docs.openstack.org and focusing on the audience for each type of
manual.

Regarding something specific below:

On Mon, Feb 14, 2011 at 9:20 AM, Anne Gentle <anne@xxxxxxxxxxxxx> wrote:
> 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!

This is very important. For developers, the important thing is: "write
code, ensure it has docstrings".

IMHO, we should not be letting *any* significant new code into
OpenStack projects without:

a) docstrings for all methods -- these turn into our API
documentation, so they are critical
b) Full RST docs for any new feature added. No exceptions.

Cheers,

Jay