Open Stack

On Thu, Aug 1, 2013 at 2:36 PM, Nermina Miller <nerminamiller at gmail.com>wrote:

> +1 for file naming. (Are sections considered separate files?) Have you all
> thought any further about adding an index? Thanks! - Nermina
>
>
Sections can definitely be separate and it's really nice to have "all one
page" sections. I'd like them to be written in such a way that we avoid
that "tiny little paragraph on a page" problem that users have identified.

Also, I think that manually indexing is just more work than we want right
now. To me, there are way too many quality issues to have any resources
work on an index. Plus, I only like human-made indexes, not machine-made.
That said, I'm certain that the truly book artifacts will get an index,
such as when we get a custom edit from O'Reilly on a book. Anyone else have
a strong opinion?
Anne


>
> On Thu, Aug 1, 2013 at 2:21 PM, Diane Fleming <diane.fleming at rackspace.com
> > wrote:
>
>>   I think it's a good practice to also add the content type to the file
>> name, like this:
>>
>>  section_nova_commands.xml -> for a section
>> ch_nova_overview.xml -> for a chapter
>> app_nova_commands.xml -> for an appendix
>>
>>  But whatever convention you come up with, document it on the
>> documentation wiki for future reference!
>>
>>  thanks,
>>
>>
>>   *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: Anne Gentle <annegentle at justwriteclick.com>
>> Date: Thursday, August 1, 2013 9:49 AM
>> To: Steve Gordon <sgordon at redhat.com>
>> Cc: Diane Fleming <diane.fleming at rackspace.com>, "
>> openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org>
>>
>> Subject: Re: [Openstack-docs] Common content strategy?
>>
>>
>>
>>
>> On Thu, Aug 1, 2013 at 9:32 AM, Steve Gordon <sgordon at redhat.com> wrote:
>>
>>>  ----- Original Message -----
>>> > From: "Anne Gentle" <annegentle at justwriteclick.com>
>>> > To: "Diane Fleming" <diane.fleming at rackspace.com>
>>> > Cc: "Steve Gordon" <sgordon at redhat.com>,
>>> openstack-docs at lists.openstack.org
>>> > Sent: Wednesday, July 31, 2013 3:36:51 PM
>>> > Subject: Re: [Openstack-docs] Common content strategy?
>>> >
>>> > On Wed, Jul 31, 2013 at 1:32 PM, Diane Fleming
>>> > <diane.fleming at rackspace.com>wrote:
>>> >
>>> > > Steve,
>>> > >
>>> > >
>>> > > Good points.
>>> > >
>>> > > I have no objections to you moving shared content into the "common"
>>> > > directory.
>>> > >
>>> > > I will move my "common" files into common this afternoon. (The CLI
>>> guide
>>> > > is going away - I just wanted it to build successfully until I got
>>> the end
>>> > > and admin user guides sorted out - so I sources files for the CLI
>>> guide
>>> > > from the user guide.)
>>> > >
>>> > > Once I move my files, you can continue moving anything else that
>>> should go
>>> > > there as you see fit!
>>> > >
>>> > > Thanks,
>>> > >
>>> > >
>>> > > 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
>>> > >
>>> > >
>>> > >
>>> > >
>>> > >
>>> > >
>>> > > On 7/31/13 1:20 PM, "Steve Gordon" <sgordon at redhat.com> wrote:
>>> > >
>>> > > >Hi all,
>>> > > >
>>> > > >In the lead up to the Grizzly release I made a handful of commits
>>> to move
>>> > > >shared content into the common directory, where it was not already
>>> there.
>>> > > >This had the effect of:
>>> > > >
>>> > > >- Making it more obvious which content was actually shared (in one
>>> case I
>>> > > >even found a file inside the openstack-compute-admin folder that
>>> was no
>>> > > >longer used in that guide at all, but was used by others).
>>> > >
>>> >
>>> > Great find. Would you mind another search round for files not being
>>> used
>>> > anywhere at all and patching to remove those?
>>>
>>>  Yes I will look into this further, obviously I want to be very sure
>>> something isn't included from somewhere before removing it :).
>>>
>>> > > >- Making it easier for me to transform/build with Publican (an
>>> admittedly
>>> > > >selfish reason but listing for completeness :)).
>>> > > >
>>> > >
>>> >
>>> > Sure, good reason!
>>> >
>>> >
>>> > > >Looking at the state of the repository as it stands today I have
>>> noticed
>>> > > >that a few instances of the following have been creeping back in as
>>> a
>>> > > >result of the restructuring efforts:
>>> > > >
>>> > > >- Content that has become common (linked in to multiple guides) but
>>> not
>>> > > >been moved to a location beneath the "common" folder (I'm ignoring
>>> here
>>> > > >the case where the cli-guide now largely includes content from the
>>> > > >user-guide folder as I believe the cli-guide is effectively now
>>> part of
>>> > > >the user-guide effort?).
>>> > >
>>> >
>>> > Yep, Diane's on it.
>>> >
>>> >
>>> > >  >- Content in the "common" folder that itself links in content from
>>> other
>>> > > >guides - effectively resulting in (1).
>>> > > >
>>> > > >I was wondering whether there are any objections to me continuing to
>>> > > >submit patches to move common content falling into these categories
>>> into
>>> > > >common (and of course update the relevant xi:includes)? There are
>>> by no
>>> > > >means a lot of these but I feel like it's probably easier to keep
>>> on top
>>> > > >of them as they come to light rather than waiting - that is if
>>> others
>>> > > >agree it's not problematic for me to be doing this. I was also
>>> wondering
>>> > > >if there might be a need to define a deeper taxonomy for content
>>> under
>>> > > >the "common" folder?
>>> > >
>>> >
>>> > No objections at all, I love this cleanup effort.
>>> >
>>> > For a deeper taxonomy, do you mean you'll put more folders in to help
>>> show
>>> > where it's reused? Or some file renaming? Let me know your thoughts
>>> there
>>> > so when I review I know what the taxonomy will be.
>>>
>>>  This was really an open-ended question. At the moment *most* of the
>>> files in there are named such that they are prefixed by the name of the
>>> project/technology they relate to, simply applying this consistently might
>>> be enough to tidy things up rather than going into any additional nesting
>>> of folders etc.
>>>
>>>
>>  Big plus 1 from me for more consistency in naming. I keep meaning to do
>> that clean up but I think I'll focus on doc bugs if you can work on a
>> naming cleanup.
>>
>>  Thanks!
>> Anne
>>
>>
>>> Thanks,
>>>
>>> Steve
>>>
>>
>>
>>
>>  --
>> Anne Gentle
>> annegentle at justwriteclick.com
>>
>> _______________________________________________
>> Openstack-docs mailing list
>> Openstack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>>
>
>
> --
> Thank you!
>
> Nermina Miller
> Tech Writer and Editor
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130801/125c85ba/attachment-0001.html>