Open Stack

Nermina,

What do you see as the advantage of an index? What does it give  you that search or TOCs do not? (I know you got feedback that people want them, but I'm just curious about your opinion.)

I use to be a big advocate of them, but I see that most companies have abandoned them. (Look at amazon docs and other API docs.)

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: Nermina Miller <nerminamiller at gmail.com<mailto:nerminamiller at gmail.com>>
Date: Thursday, August 1, 2013 3:01 PM
To: Anne Gentle <annegentle at justwriteclick.com<mailto:annegentle at justwriteclick.com>>
Cc: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>>, Steve Gordon <sgordon at redhat.com<mailto:sgordon at redhat.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?

As far as indexing, we could take an "agile" approach and apply them as we work on bugs and publish only when the index is deemed complete. We could begin by applying the tags to chapter, appendix, and section heads.


On Thu, Aug 1, 2013 at 3:47 PM, Anne Gentle <annegentle at justwriteclick.com<mailto:annegentle at justwriteclick.com>> 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>



--
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/1beb9de2/attachment-0001.html>