openstack team mailing list archive
Mailing list archive
Re: documentation contributions
Thierry Carrez <thierry@xxxxxxxxxxxxx>
Mon, 14 Feb 2011 16:25:24 +0100
Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:188.8.131.52) Gecko/20101208 Thunderbird/3.1.7
Jay Pipes wrote:
> 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.
One issue is that if you see the split in Anne's description, features
documentation needs to be added to the admin docs (Docbook), not really
the developer docs (RST), so it's in a separate branch. That makes it
harder to enforce...
IIUC the dev docs should contain docstrings and a few developer-oriented
info like "how to do i18n right" or "how we do logging in code" and
other "this is how we do it" topics. If we add features documentation,
that duplicates the work in the admin docs (Docbook) and increases user
confusion as to "where is *the* doc".
Thierry Carrez (ttx)
Release Manager, OpenStack