Open Stack

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<mailto:annegentle at justwriteclick.com>>
Date: Thursday, August 1, 2013 9:49 AM
To: Steve Gordon <sgordon at redhat.com<mailto:sgordon at redhat.com>>
Cc: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto: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<mailto:sgordon at redhat.com>> wrote:
----- Original Message -----
> From: "Anne Gentle" <annegentle at justwriteclick.com<mailto:annegentle at justwriteclick.com>>
> To: "Diane Fleming" <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>>
> Cc: "Steve Gordon" <sgordon at redhat.com<mailto:sgordon at redhat.com>>, openstack-docs at lists.openstack.org<mailto: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<mailto: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<mailto:diane.fleming at rackspace.com>
> > Cell  512.323.6799<tel:512.323.6799>
> > Office 512.874.1260<tel:512.874.1260>
> > Skype drfleming0227
> > Google-plus diane.fleming at gmail.com<mailto:diane.fleming at gmail.com>
> >
> >
> >
> >
> >
> >
> > On 7/31/13 1:20 PM, "Steve Gordon" <sgordon at redhat.com<mailto: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<mailto:annegentle at justwriteclick.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130801/4a85295a/attachment-0001.html>