Open Stack

+1 for file naming. (Are sections considered separate files?) Have you all
thought any further about adding an index? Thanks! - Nermina


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