Open Stack

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

> Makes sense! However, I think services other than neutron need some
> restructuring (mostly reordering of steps) to improve flow. For example,
> the nova controller steps bounce around between prerequisites and editing
> configuration files. We should first provide all of the prerequisites, then
> install packages and configure the service, and finally verify
> functionality (when applicable).
>

Yes, this sort of change sounds reasonable.


> I suspect much of this "jumbling" came as a side-effect of integrating
> tools such as openstack-config and openstack-db with generic editing of
> configuration files. Removal of these tools should help us provide a
> consistent structure among services for all distributions.
>

Agreed.


> For the installation guide improvements project, we should evaluate the
> complexity of each service to determine if multiple procedures improve the
> flow of installation/configuration.
>

Mostly my sense of the feedback from readers is "tell me what goes on which
node" so any improvement in that way is welcomed. My concern was that you
were chasing consistency for the sake of it.

Keystone appears to work with one procedure for installation/configuration,
> so we'll run with it after I make some additional minor changes from
> comments in a similar patch.
>
>
> On Thu, Jun 12, 2014 at 10:16 AM, Anne Gentle <anne at openstack.org> wrote:
>
>>
>>
>>
>> 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/f03455b6/attachment-0001.html>