Open Stack

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/20140203/2c026ee0/attachment.html>