Open Stack

I appreciate your help.
I’m looking forward to the details you notice me…

Thanks.
Kei

From: annegentle at justwriteclick.com [mailto:annegentle at justwriteclick.com] On Behalf Of Anne Gentle
Sent: Wednesday, February 16, 2011 3:33 AM
To: RDH 桝本 圭(ＩＴアーキ＆セキュ技術)
Cc: jaypipes at gmail.com; thierry at openstack.org; openstack at lists.launchpad.net
Subject: Re: [Openstack] documentation contributions


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 at openstack.org<mailto:anne at openstack.org>
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 at nttdata.co.jp<mailto:masumotok at nttdata.co.jp>> 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<http://nttdata.co.jp>@lists.launchpad.net<http://lists.launchpad.net> [mailto:openstack-bounces+masumotok<mailto:openstack-bounces%2Bmasumotok>=nttdata.co.jp<http://nttdata.co.jp>@lists.launchpad.net<http://lists.launchpad.net>] On Behalf Of Jay Pipes
Sent: Tuesday, February 15, 2011 12:29 AM
To: Thierry Carrez
Cc: openstack at lists.launchpad.net<mailto:openstack at lists.launchpad.net>
Subject: Re: [Openstack] documentation contributions

On Mon, Feb 14, 2011 at 10:25 AM, Thierry Carrez <thierry at openstack.org<mailto:thierry at openstack.org>> 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<https://launchpad.net/%7Eopenstack>
> Post to     : openstack at lists.launchpad.net<mailto:openstack at lists.launchpad.net>
> Unsubscribe : https://launchpad.net/~openstack<https://launchpad.net/%7Eopenstack>
> More help   : https://help.launchpad.net/ListHelp
>

_______________________________________________
Mailing list: https://launchpad.net/~openstack<https://launchpad.net/%7Eopenstack>
Post to     : openstack at lists.launchpad.net<mailto:openstack at lists.launchpad.net>
Unsubscribe : https://launchpad.net/~openstack<https://launchpad.net/%7Eopenstack>
More help   : https://help.launchpad.net/ListHelp
_______________________________________________
Mailing list: https://launchpad.net/~openstack<https://launchpad.net/%7Eopenstack>
Post to     : openstack at lists.launchpad.net<mailto:openstack at lists.launchpad.net>
Unsubscribe : https://launchpad.net/~openstack<https://launchpad.net/%7Eopenstack>
More help   : https://help.launchpad.net/ListHelp

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack/attachments/20110216/6514b343/attachment.html>