[Openstack-docs] Common content strategy?
Tom Fifield
tom at openstack.org
Thu Aug 1 19:53:54 UTC 2013
Just quickly on the crazy linking that's going on right now.
I'm one of the worst offenders of breaking the model, but I believe
there's good reason ... in doing the restructure, I'm trying to keep
current things in place, but note that they'll be subsumed as further
progress is made.
If there's a big effort to push content into the common folder right
now, you'll end up with most of the compute admin manual and the config
reference in the common folder.
Suggestion: hold off for a bit and do the cleanup after the worst of the
restructure is over?
Regards,
Tom
On 02/08/13 05:47, Anne Gentle wrote:
>
>
>
> On Thu, Aug 1, 2013 at 2:36 PM, Nermina Miller <nerminamiller at gmail.com
> <mailto: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 <mailto: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 <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>
>
> 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>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> <mailto: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 <mailto:annegentle at justwriteclick.com>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
More information about the Openstack-docs
mailing list