openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Thanks for sending this, Masumotok! I was planning to reach out to you to
see what you had so far. I'll work with you to get the wiki page into RST
and/or DocBook and will send you a separate email for the details.

Thanks,
Anne


*Anne Gentle*
anne@xxxxxxxxxxxxx
 my blog <http://justwriteclick.com/> | my
book<http://xmlpress.net/publications/conversation-community/>|
LinkedIn <http://www.linkedin.com/in/annegentle> |
Delicious<http://del.icio.us/annegentle>|
Twitter <http://twitter.com/annegentle>
On Tue, Feb 15, 2011 at 2:43 AM, <masumotok@xxxxxxxxxxxxx> wrote:

> it is slightly out-of topic, but it might be good chance to say this,
> excuse me.. :)
>
> > For instance, when live-migrations goes in, I want to see some RST
> > documentation that explains the concepts involved to developers,
> > including how live migrations differs from, say, snapshotting.
>
> For admins:
>  http://wiki.openstack.org/LiveMigrationUsage
>
> For Devs:
>  Overall design document exists at :
>  <
> http://wiki.openstack.org/LiveMigration?action=AttachFile&do=view&target=20110203cactus-migration-live.pdf
> >
>
>  Regarding to RST docs, I'm reading other rst docs to decide what to write.
>  Please hold on..
>
> -----Original Message-----
> From: openstack-bounces+masumotok=nttdata.co.jp@xxxxxxxxxxxxxxxxxxx[mailto:
> openstack-bounces+masumotok=nttdata.co.jp@xxxxxxxxxxxxxxxxxxx] On Behalf
> Of Jay Pipes
> Sent: Tuesday, February 15, 2011 12:29 AM
> To: Thierry Carrez
> Cc: openstack@xxxxxxxxxxxxxxxxxxx
> Subject: Re: [Openstack] documentation contributions
>
> On Mon, Feb 14, 2011 at 10:25 AM, Thierry Carrez <thierry@xxxxxxxxxxxxx>
> wrote:
> > 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
> >
> > Agreed.
> >
> >> 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...
>
> Sorry, I mean RST docs for concepts introduced by a feature patch.
>
> For instance, when live-migrations goes in, I want to see some RST
> documentation that explains the concepts involved to developers,
> including how live migrations differs from, say, snapshotting.
>
> For user and admin documentation, Anne can ready the concept RST docs
> in the developer documentation and work with the authors to produce
> user and admin-focused docbook manuals.
>
> my 2 cents and all that,
> -jay
>
>
> > 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
> >
> > _______________________________________________
> > Mailing list: https://launchpad.net/~openstack
> > Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> > Unsubscribe : https://launchpad.net/~openstack
> > More help   : https://help.launchpad.net/ListHelp
> >
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>