<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">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>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><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 class="h5">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 class="h5">
<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 class="im">_______________________________________________<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 class=""><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><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>