Open Stack

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<mailto:slong at redhat.com>>
Date: Monday, February 3, 2014 5:02 PM
To: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>
Cc: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>>, Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>, Steve Gordon <sgordon at redhat.com<mailto: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, Australia
slong at redhat.com<mailto:slong at redhat.com> | irc: slong

________________________________
From: "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>>
To: "Diane Fleming" <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>>
Cc: "Summer Long" <slong at redhat.com<mailto:slong at redhat.com>>, "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>>, openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>, "Steve Gordon" <sgordon at redhat.com<mailto: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<mailto: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<mailto:slong at redhat.com>> wrote:
>
>
>
> --
> Summer Long
> OpenStack Documentation Lead
> Engineering Content Services
>
> Red Hat Asia Pacific
> Brisbane, Austral ia
> slong at redhat.com<mailto:slong at redhat.com> | irc: slong
>
> ----- Original Message -----
>> From: "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>>
>> To: "Summer Long" <slong at redhat.com<mailto:slong at redhat.com>>
>> Cc: "Diane Fleming" <diane.fleming at RACKSPACE.COM<mailto:diane.fleming at RACKSPACE.COM>>, "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>>,
>> openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>, "Steve Gordon" <sgordon at redhat.com<mailto: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<mailto:aj at suse.com>>
>>>> To: "Diane Fleming" <diane.fleming at RACKSPACE.COM<mailto:diane.fleming at RACKSPACE.COM>>, "Anne Gentle"
>>>> <anne at openstack.org<mailto:anne at openstack.org>>
>>>> Cc: openstack-docs at lists.openstack.org<mailto: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<http://suse.com>,opensuse.org<http://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/f1c12246/attachment.html>