<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<div>
<div>
<div>Nermina, </div>
<div><br>
</div>
<div>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.)</div>
<div><br>
</div>
<div>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.)</div>
<div><br>
</div>
<div>
<div>
<div style="color: rgb(0, 0, 0); "><font class="Apple-style-span" color="rgb(0, 0, 0)" face="Apple Chancery"><i>Diane</i></font></div>
<div style="font-family: Calibri, sans-serif; font-size: 14px; color: rgb(0, 0, 0); ">
<font class="Apple-style-span" color="rgb(0, 0, 0)"><i>----------------------------------------------</i></font></div>
<div style="font-family: Calibri, sans-serif; font-size: 14px; color: rgb(0, 0, 0); ">
<font class="Apple-style-span" color="rgb(0, 0, 0)">Diane Fleming</font></div>
<div style="font-family: Calibri, sans-serif; font-size: 14px; ">
<div style="color: rgb(0, 0, 0); ">Software Developer II - US</div>
</div>
diane.fleming@rackspace.com</div>
<div>Cell 512.323.6799</div>
<div>Office 512.874.1260<br>
<span class="Apple-style-span" style="font-family: Calibri, sans-serif; ">
<div style="font-family: Calibri, sans-serif; font-size: 14px; ">
<div style="color: rgb(0, 0, 0); ">Skype drfleming0227</div>
<div style="color: rgb(0, 0, 0); ">Google-plus diane.fleming@gmail.com</div>
</div>
</span></div>
</div>
</div>
</div>
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<div style="font-family:Calibri; font-size:11pt; text-align:left; color:black; BORDER-BOTTOM: medium none; BORDER-LEFT: medium none; PADDING-BOTTOM: 0in; PADDING-LEFT: 0in; PADDING-RIGHT: 0in; BORDER-TOP: #b5c4df 1pt solid; BORDER-RIGHT: medium none; PADDING-TOP: 3pt">
<span style="font-weight:bold">From: </span>Nermina Miller <<a href="mailto:nerminamiller@gmail.com">nerminamiller@gmail.com</a>><br>
<span style="font-weight:bold">Date: </span>Thursday, August 1, 2013 3:01 PM<br>
<span style="font-weight:bold">To: </span>Anne Gentle <<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>><br>
<span style="font-weight:bold">Cc: </span>Diane Fleming <<a href="mailto:diane.fleming@rackspace.com">diane.fleming@rackspace.com</a>>, Steve Gordon <<a href="mailto:sgordon@redhat.com">sgordon@redhat.com</a>>, "<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>"
<<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>><br>
<span style="font-weight:bold">Subject: </span>Re: [Openstack-docs] Common content strategy?<br>
</div>
<div><br>
</div>
<div>
<div>
<div dir="ltr">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.</div>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Thu, Aug 1, 2013 at 3:47 PM, Anne Gentle <span dir="ltr">
<<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr"><br>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">
<div class="im">On Thu, Aug 1, 2013 at 2:36 PM, Nermina Miller <span dir="ltr"><<a href="mailto:nerminamiller@gmail.com" target="_blank">nerminamiller@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr">+1 for file naming. (Are sections considered separate files?) Have you all thought any further about adding an index? Thanks! - Nermina</div>
<div class="gmail_extra"><br>
</div>
</blockquote>
<div><br>
</div>
</div>
<div>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.</div>
<div><br>
</div>
<div>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?</div>
<div>Anne</div>
<div>
<div class="h5">
<div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div class="gmail_extra"><br>
<div class="gmail_quote">
<div>
<div>On Thu, Aug 1, 2013 at 2:21 PM, Diane Fleming <span dir="ltr"><<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>></span> wrote:<br>
</div>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div>
<div>
<div style="font-size:14px;font-family:Calibri,sans-serif;word-wrap:break-word">
<div>
<div>
<div>I think it's a good practice to also add the content type to the file name, like this:</div>
<div><br>
</div>
<div>section_nova_commands.xml -> for a section</div>
<div>ch_nova_overview.xml -> for a chapter</div>
<div>app_nova_commands.xml -> for an appendix</div>
<div><br>
</div>
<div>But whatever convention you come up with, document it on the documentation wiki for future reference!</div>
<div>
<div><br>
</div>
<div>thanks,</div>
<div><br>
</div>
<div><br>
</div>
<div>
<div>
<div><font color="rgb(0, 0, 0)" face="Apple Chancery"><i>Diane</i></font></div>
<div style="font-size:14px;font-family:Calibri,sans-serif"><font color="rgb(0, 0, 0)"><i>----------------------------------------------</i></font></div>
<div style="font-size:14px;font-family:Calibri,sans-serif"><font color="rgb(0, 0, 0)">Diane Fleming</font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px">
<div>Software Developer II - US</div>
</div>
<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a></div>
<div>Cell <a href="tel:512.323.6799" value="+15123236799" target="_blank">512.323.6799</a></div>
<div>Office <a href="tel:512.874.1260" value="+15128741260" target="_blank">512.874.1260</a><br>
<span style="font-family: Calibri, sans-serif; ">
<div style="font-family:Calibri,sans-serif;font-size:14px">
<div>Skype drfleming0227</div>
<div>Google-plus <a href="mailto:diane.fleming@gmail.com" target="_blank">diane.fleming@gmail.com</a></div>
</div>
</span></div>
</div>
</div>
</div>
</div>
<div><br>
</div>
<span>
<div style="border-width:1pt medium medium;border-style:solid none none;padding:3pt 0in 0in;text-align:left;font-size:11pt;font-family:Calibri;border-top-color:rgb(181,196,223)">
<span style="font-weight:bold">From: </span>Anne Gentle <<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>><br>
<span style="font-weight:bold">Date: </span>Thursday, August 1, 2013 9:49 AM<br>
<span style="font-weight:bold">To: </span>Steve Gordon <<a href="mailto:sgordon@redhat.com" target="_blank">sgordon@redhat.com</a>><br>
<span style="font-weight:bold">Cc: </span>Diane Fleming <<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>>, "<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>"
<<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>>
<div>
<div><br>
<span style="font-weight:bold">Subject: </span>Re: [Openstack-docs] Common content strategy?<br>
</div>
</div>
</div>
<div>
<div>
<div><br>
</div>
<div>
<div>
<div dir="ltr"><br>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Thu, Aug 1, 2013 at 9:32 AM, Steve Gordon <span dir="ltr">
<<a href="mailto:sgordon@redhat.com" target="_blank">sgordon@redhat.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div>
<div>----- Original Message -----<br>
> From: "Anne Gentle" <<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>><br>
> To: "Diane Fleming" <<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>><br>
> Cc: "Steve Gordon" <<a href="mailto:sgordon@redhat.com" target="_blank">sgordon@redhat.com</a>>,
<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a><br>
> Sent: Wednesday, July 31, 2013 3:36:51 PM<br>
> Subject: Re: [Openstack-docs] Common content strategy?<br>
><br>
> On Wed, Jul 31, 2013 at 1:32 PM, Diane Fleming<br>
> <<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>>wrote:<br>
><br>
> > Steve,<br>
> ><br>
> ><br>
> > Good points.<br>
> ><br>
> > I have no objections to you moving shared content into the "common"<br>
> > directory.<br>
> ><br>
> > I will move my "common" files into common this afternoon. (The CLI guide<br>
> > is going away - I just wanted it to build successfully until I got the end<br>
> > and admin user guides sorted out - so I sources files for the CLI guide<br>
> > from the user guide.)<br>
> ><br>
> > Once I move my files, you can continue moving anything else that should go<br>
> > there as you see fit!<br>
> ><br>
> > Thanks,<br>
> ><br>
> ><br>
> > Diane<br>
> > ----------------------------------------------<br>
> > Diane Fleming<br>
> > Software Developer II - US<br>
> ><br>
> > <a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a><br>
> > Cell <a href="tel:512.323.6799" value="+15123236799" target="_blank">512.323.6799</a><br>
> > Office <a href="tel:512.874.1260" value="+15128741260" target="_blank">512.874.1260</a><br>
> > Skype drfleming0227<br>
> > Google-plus <a href="mailto:diane.fleming@gmail.com" target="_blank">diane.fleming@gmail.com</a><br>
> ><br>
> ><br>
> ><br>
> ><br>
> ><br>
> ><br>
> > On 7/31/13 1:20 PM, "Steve Gordon" <<a href="mailto:sgordon@redhat.com" target="_blank">sgordon@redhat.com</a>> wrote:<br>
> ><br>
> > >Hi all,<br>
> > ><br>
> > >In the lead up to the Grizzly release I made a handful of commits to move<br>
> > >shared content into the common directory, where it was not already there.<br>
> > >This had the effect of:<br>
> > ><br>
> > >- Making it more obvious which content was actually shared (in one case I<br>
> > >even found a file inside the openstack-compute-admin folder that was no<br>
> > >longer used in that guide at all, but was used by others).<br>
> ><br>
><br>
> Great find. Would you mind another search round for files not being used<br>
> anywhere at all and patching to remove those?<br>
<br>
</div>
</div>
Yes I will look into this further, obviously I want to be very sure something isn't included from somewhere before removing it :).<br>
<div>
<div><br>
> > >- Making it easier for me to transform/build with Publican (an admittedly<br>
> > >selfish reason but listing for completeness :)).<br>
> > ><br>
> ><br>
><br>
> Sure, good reason!<br>
><br>
><br>
> > >Looking at the state of the repository as it stands today I have noticed<br>
> > >that a few instances of the following have been creeping back in as a<br>
> > >result of the restructuring efforts:<br>
> > ><br>
> > >- Content that has become common (linked in to multiple guides) but not<br>
> > >been moved to a location beneath the "common" folder (I'm ignoring here<br>
> > >the case where the cli-guide now largely includes content from the<br>
> > >user-guide folder as I believe the cli-guide is effectively now part of<br>
> > >the user-guide effort?).<br>
> ><br>
><br>
> Yep, Diane's on it.<br>
><br>
><br>
> > >- Content in the "common" folder that itself links in content from other<br>
> > >guides - effectively resulting in (1).<br>
> > ><br>
> > >I was wondering whether there are any objections to me continuing to<br>
> > >submit patches to move common content falling into these categories into<br>
> > >common (and of course update the relevant xi:includes)? There are by no<br>
> > >means a lot of these but I feel like it's probably easier to keep on top<br>
> > >of them as they come to light rather than waiting - that is if others<br>
> > >agree it's not problematic for me to be doing this. I was also wondering<br>
> > >if there might be a need to define a deeper taxonomy for content under<br>
> > >the "common" folder?<br>
> ><br>
><br>
> No objections at all, I love this cleanup effort.<br>
><br>
> For a deeper taxonomy, do you mean you'll put more folders in to help show<br>
> where it's reused? Or some file renaming? Let me know your thoughts there<br>
> so when I review I know what the taxonomy will be.<br>
<br>
</div>
</div>
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.<br>
<br>
</blockquote>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>Thanks!</div>
<div>Anne</div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Thanks,<br>
<br>
Steve<br>
</blockquote>
</div>
<br>
<br clear="all">
<div><br>
</div>
-- <br>
Anne Gentle<br>
<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div>
</div>
</div>
</div>
</div>
</span></div>
<br>
</div>
</div>
<div>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br>
</div>
</blockquote>
</div>
<span><font color="#888888"><br>
<br clear="all">
<div><br>
</div>
-- <br>
<div dir="ltr">Thank you!
<div><br>
</div>
<div>Nermina Miller</div>
<div>Tech Writer and Editor</div>
</div>
</font></span></div>
</blockquote>
</div>
</div>
</div>
<span class="HOEnZb"><font color="#888888"><br>
<br clear="all">
<div><br>
</div>
-- <br>
Anne Gentle<br>
<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></font></span></div>
</div>
</blockquote>
</div>
<br>
<br clear="all">
<div><br>
</div>
-- <br>
<div dir="ltr">Thank you!
<div><br>
</div>
<div>Nermina Miller</div>
<div>Tech Writer and Editor</div>
</div>
</div>
</div>
</div>
</span>
</body>
</html>