Open Stack

On Thu, Jun 12, 2014 at 11:01 AM, Matt Kassawara <mkassawara at gmail.com>
wrote:

> Anyone else want to comment? This issue affects most of the installation
> guide improvement patches.
>
>
Yes of course. :)

The non-neutron portions of the guide are well-written and shouldn't really
be revised much. They've been reviewed and tested for a long time and that
simplicity should remain.

The neutron portions of the guide can be revised but they can be written
differently due to the increasing complexity.

So I agree with Diane that strict consistency isn't required here, and is
not a value-add. The services are quite different and the history of the
guide sections warrants only revising the neutron procedures.

Anne


> On Wed, Jun 11, 2014 at 1:33 PM, Diane Fleming <
> diane.fleming at rackspace.com> wrote:
>
>>   Thanks Matt.
>>
>>  I'm in favor of breaking procedures that are longer than 10 steps into
>> smaller procedures. Otherwise, when possible, use a single procedure.
>>
>>  I don't think consistency gains us much, if anything, in this case.
>>
>>  Here's some good general guidance about procedures:
>>
>>
>> http://www.helpscribe.com/2008/01/11-tips-for-writing-incredibly-useful.html
>>
>>   *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: Matt Kassawara <mkassawara at gmail.com>
>> Date: Wednesday, June 11, 2014 2:03 PM
>> To: "openstack-docs at lists.openstack.org" <
>> openstack-docs at lists.openstack.org>
>> Subject: [Openstack-docs] Installation and configuration section
>> structure
>>
>>   Prior to the Icehouse installation guide networking updates project,
>> the structure for most installation and configuration sections consisted of
>> one procedure containing steps/substeps. While working on the networking
>> updates project, I found this structure difficult for us to code and for
>> our audience to follow with more complex services such as neutron. After
>> trying some variants of the original structure, I eventually decided to
>> break each group of related steps into separate procedures. To provide our
>> audience with consistency, I think we should implement this structure
>> throughout the installation guide during the improvement project. However,
>> this structure leans toward overkill for simpler services such as keystone.
>> We need to determine whether we stick with consistency or adjust structure
>> based on service complexity. Please take a look at the following examples
>> of each structure and provide your opinions.
>>
>>  Separate procedures:
>>
>>
>> http://docs.openstack.org/icehouse/install-guide/install/apt/content/neutron-ml2-network-node.html
>>
>>
>> http://docs-draft.openstack.org/59/96059/4/check/gate-openstack-manuals-tox-doc-publish-checkbuild/32a4a38/publish-docs/trunk/install-guide/install/apt/content/keystone-install.html
>>
>>  One procedure:
>>
>>
>> http://docs-draft.openstack.org/59/96059/10/check/gate-openstack-manuals-tox-doc-publish-checkbuild/d804200/publish-docs/trunk/install-guide/install/apt/content/keystone-install.html
>>
>>  Matt
>>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140612/02b38abb/attachment-0001.html>