Open Stack

Anyone else want to comment? This issue affects most of the installation
guide improvement patches.


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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140612/65c54f3c/attachment.html>