Open Stack

Hi Diane, 
Could swear I replied, but it's still in my inbox, so... 

Yes, I understand your argument, definitely. And have given up the idea of a complete reference, no probs. :) 
Summer 

-- 
Summer Long 
OpenStack Documentation Lead 
Engineering Content Services 

Red Hat Asia Pacific 
Brisbane, Austral ia 
slong at redhat.com | irc: slong 

----- Original Message -----

> From: "Diane Fleming" <diane.fleming at rackspace.com>
> To: "Summer Long" <slong at redhat.com>, "Anne Gentle" <anne at openstack.org>
> Cc: "Andreas Jaeger" <aj at suse.com>, openstack-docs at lists.openstack.org,
> "Steve Gordon" <sgordon at redhat.com>
> Sent: Wednesday, February 5, 2014 12:52:05 AM
> Subject: Re: [Openstack-docs] Proposal: CLI Reference manual

> Summer,

> I see what you're after here, but it's really apples and oranges. The only
> commonality is that CLI Reference and Config Reference are reference
> documentation. Different audiences, different types of reference material.

> my 2 cents

> Diane
> ----------------------------------------------
> Diane Fleming
> Software Developer II - US
> diane.fleming at rackspace.com
> Cell 512.323.6799
> Office 512.874.1260
> Skype drfleming0227
> Google-plus diane.fleming at gmail.com

> From: Summer Long < slong at redhat.com >
> Date: Monday, February 3, 2014 5:02 PM
> To: Anne Gentle < anne at openstack.org >
> Cc: Diane Fleming < diane.fleming at rackspace.com >, Andreas Jaeger <
> aj at suse.com >, " openstack-docs at lists.openstack.org " <
> openstack-docs at lists.openstack.org >, Steve Gordon < sgordon at redhat.com >
> Subject: Re: [Openstack-docs] Proposal: CLI Reference manual

> Trying to be creative here with another solution, but nothing is arriving. Do
> believe it's a good step to get rid of the EUG/AUG duplication, and you
> can't pick one over the other since the audience is so integral.

> Am really just kicking against the separate book for a reference list where,
> again, a listing by component is contained. Wouldn't it be nice to have one
> place where all component bits could be found.....OpenStack Component
> Reference?

> /me bowing to the many.
> Summer

> --
> Summer Long
> OpenStack Documentation Lead
> Engineering Content Services

> Red Hat Asia Pacific
> Brisbane, Austral ia
> slong at redhat.com | irc: slong

> ----- Original Message -----

> > From: "Anne Gentle" < anne at openstack.org >
> 
> > To: "Diane Fleming" < diane.fleming at rackspace.com >
> 
> > Cc: "Summer Long" < slong at redhat.com >, "Andreas Jaeger" < aj at suse.com >,
> > openstack-docs at lists.openstack.org , "Steve Gordon" < sgordon at redhat.com >
> 
> > Sent: Tuesday, February 4, 2014 12:14:02 AM
> 
> > Subject: Re: [Openstack-docs] Proposal: CLI Reference manual
> 

> > On Mon, Feb 3, 2014 at 8:09 AM, Diane Fleming < diane.fleming at rackspace.com
> > >
> > wrote:
> 

> > > I don't think CLI reference should be part of config reference. Two
> > > different
> > > audiences and CLI commands are used by a broad audience who would
> > > probably
> > > never think to look in that book for CLI info (even if the title
> > > changes).
> > > My two cents!
> > 
> 

> > Agreed -- I think the keyword of that title is Configuration so people
> > wouldn't think to look there. Let's not expose our autodoc victory to our
> > readers by combining the two just because they're both automated. :)
> 

> > Summer, I think the heart of your concern lies with the admin/end-user
> > split?
> > Is there another way to address that?
> 

> > Anne
> 

> > > Sent from my iPhone
> > 
> 

> > > > On Feb 3, 2014, at 12:53 AM, "Summer Long" < slong at redhat.com > wrote:
> > 
> 
> > > >
> > 
> 
> > > >
> > 
> 
> > > >
> > 
> 
> > > > --
> > 
> 
> > > > Summer Long
> > 
> 
> > > > OpenStack Documentation Lead
> > 
> 
> > > > Engineering Content Services
> > 
> 
> > > >
> > 
> 
> > > > Red Hat Asia Pacific
> > 
> 
> > > > Brisbane, Austral ia
> > 
> 
> > > > slong at redhat.com | irc: slong
> > 
> 
> > > >
> > 
> 
> > > > ----- Original Message -----
> > 
> 
> > > >> From: "Andreas Jaeger" < aj at suse.com >
> > 
> 
> > > >> To: "Summer Long" < slong at redhat.com >
> > 
> 
> > > >> Cc: "Diane Fleming" < diane.fleming at RACKSPACE.COM >, "Anne Gentle" <
> > > >> anne at openstack.org >,
> > 
> 
> > > >> openstack-docs at lists.openstack.org , "Steve Gordon" <
> > > >> sgordon at redhat.com
> > > >> >
> > 
> 
> > > >> Sent: Monday, February 3, 2014 4:34:44 PM
> > 
> 
> > > >> Subject: Re: [Openstack-docs] Proposal: CLI Reference manual
> > 
> 
> > > >>
> > 
> 
> > > >>> On 02/03/2014 03:59 AM, Summer Long wrote:
> > 
> 
> > > >>>
> > 
> 
> > > >>>
> > 
> 
> > > >>> ----- Original Message -----
> > 
> 
> > > >>>> From: "Andreas Jaeger" < aj at suse.com >
> > 
> 
> > > >>>> To: "Diane Fleming" < diane.fleming at RACKSPACE.COM >, "Anne Gentle"
> > 
> 
> > > >>>> < anne at openstack.org >
> > 
> 
> > > >>>> Cc: openstack-docs at lists.openstack.org
> > 
> 
> > > >>>> Sent: Friday, January 31, 2014 1:44:04 AM
> > 
> 
> > > >>>> Subject: Re: [Openstack-docs] Proposal: CLI Reference manual
> > 
> 
> > > >>>>
> > 
> 
> > > >>>>> On 01/30/2014 04:26 PM, Diane Fleming wrote:
> > 
> 
> > > >>>>> Actually, I'm fine either way – keeping it as appendix or as
> > > >>>>> separate
> > 
> 
> > > >>>>> book.
> > 
> 
> > > >>>>>
> > 
> 
> > > >>>>> But either way, I think we need to improve the formatting – I'll
> > > >>>>> open
> > > >>>>> a
> > 
> 
> > > >>>>> bug for that.
> > 
> 
> > > >>>
> > 
> 
> > > >>> And can the 'install the clients' section be removed? Clients should
> > 
> 
> > > >>> already be installed via the Installation Guide?
> > 
> 
> > > >>
> > 
> 
> > > >> Clients will be installed on machines outside of the cloud as well, so
> > > >> I
> > 
> 
> > > >> think this really belongs to the CLI reference.
> > 
> 
> > > > Yep, ok, fair enough.
> > 
> 
> > > >>
> > 
> 
> > > >>>>
> > 
> 
> > > >>>> Yes, please do open a bug. I'll see what I can do to improve it.
> > 
> 
> > > >>>>
> > 
> 
> > > >>>>> What does everyone else think about keeping command ref as
> > > >>>>> appendix,
> > > >>>>> or
> > 
> 
> > > >>>>> moving to separate book?
> > 
> 
> > > >>>>
> > 
> 
> > > >>>> I'm fine either way. Having one more guide, will not really cost us
> > 
> 
> > > >>>> more work than having it in the appendices. And having a guide would
> > 
> 
> > > >>>> give us *one* location for the content instead of currently two
> > > >>>> guides
> > 
> 
> > > >>>> with both the same large appendix.
> > 
> 
> > > >>> Definitely vote for having it
> > 
> 
> > > >>>
> > 
> 
> > > >>>>
> > 
> 
> > > >>>> And I'm even fine with removing the appendix and not having a book
> > > >>>> since
> > 
> 
> > > >>>> these are help texts users could get themselves on the command
> > > >>>> line...
> > 
> 
> > > >>>> Still, it's nice to have a common location to look it up and be
> > > >>>> aware
> > > >>>> of
> > 
> 
> > > >>>> these. And since there are no man pages for these, this it probably
> > > >>>> the
> > 
> 
> > > >>>> best way to have it,
> > 
> 
> > > >>>
> > 
> 
> > > >>> +1 on removing the CLI info from both EUG and AUG and providing links
> > 
> 
> > > >>> (really dislike bloat-by-duplication).
> > 
> 
> > > >>>
> > 
> 
> > > >>> But was there a reason for not just putting the CLI info into the
> > 
> 
> > > >>> Configuration Reference Guide?
> > 
> 
> > > >>> We're removing the HowTos from that guide, which means the whole
> > > >>> thing
> > 
> 
> > > >>> really is a reference now?
> > 
> 
> > > >>
> > 
> 
> > > >> IMO they target different personas - the admin of the cloud for the
> > 
> 
> > > >> Configuration Reference only and the CLI reference both admin and
> > > >> users,
> > 
> 
> > > > But if you do this, you're creating an admin-and-users book. Why not
> > > > just
> > > > make the Configuration Reference have that audience as well and keep
> > > > all
> > > > the automatically generated reference lists in one book? 'Configuration
> > > > and CLI Reference'
> > 
> 
> > > >
> > 
> 
> > > > cheers, Summer
> > 
> 
> > > >
> > 
> 
> > > >>
> > 
> 
> > > >> Andreas
> > 
> 
> > > >> --
> > 
> 
> > > >> Andreas Jaeger aj@{ suse.com , opensuse.org } Twitter/Identica:
> > > >> jaegerandi
> > 
> 
> > > >> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
> > 
> 
> > > >> GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
> > 
> 
> > > >> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
> > 
> 
> > > >>
> > 
> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140204/7e5583a0/attachment-0001.html>