<div dir="ltr">During the Icehouse installation guide updates project, selection of IDs in new content confused me because I couldn't find conventions or anything consistent to follow. This caused me to bring up ID issues during the audit but didn't consider the underlying filename issues. For IDs, maybe we provide some good/bad examples, but otherwise leave it open to the contributor? At any rate, I'm glad this discussion revealed a larger problem that we want to fix... filenames!</div>
<div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, May 26, 2014 at 9:17 AM, Diane Fleming <span dir="ltr"><<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div style="word-wrap:break-word;color:rgb(0,0,0);font-size:14px;font-family:Calibri,sans-serif">
<div>
<div>
<div>Matt, </div>
<div><br>
</div>
<div>I agree that whatever consistency issues we come up with should be documented on conventions page. </div>
<div><br>
</div>
<div>My suggestion was that you postpone thinking about the ID issue until you come up with reasons for changing them. It seems like everyone agrees on the file name changes, so I think it's safe to go forward with that!</div>
<div class="">
<div><br>
</div>
<div>
<div>
<div style="color:rgb(0,0,0)"><font 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 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 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>
<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 style="color:rgb(0,0,0)">Skype drfleming0227</div>
<div style="color:rgb(0,0,0)">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="font-family:Lucida Grande;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>Matt Kassawara <<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@gmail.com</a>><br>
<span style="font-weight:bold">Date: </span>Monday, May 26, 2014 10:15 AM<br>
<span style="font-weight:bold">To: </span>Diane Fleming <<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>><div><div class="h5"><br>
<span style="font-weight:bold">Subject: </span>Re: [Openstack-docs] Conventions for filenames and chapter/section IDs<br>
</div></div></div><div><div class="h5">
<div><br>
</div>
<div>
<div>
<div dir="ltr">IDs came up as a consistency issue from the installation guide audit. Since any changes would impact references and patches for other issues, I wanted to discuss the situation early in the process of improving the installation guide. Whatever
we decide for filenames and IDs, it should go into our conventions page for future reference.</div>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Mon, May 26, 2014 at 8:47 AM, Diane Fleming <span dir="ltr">
<<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div style="word-wrap:break-word;color:rgb(0,0,0);font-size:14px;font-family:Calibri,sans-serif">
<div>
<div>
<div>Matt, </div>
<div><br>
</div>
<div>What problem are you trying to solve by updating the xml:id values?</div>
<div><br>
</div>
<div>I'd start with one issue – the file names – and then figure out what you want to accomplish by changing xml:id values.</div>
<div><br>
</div>
<div>I personally don't see much value-add with updates to the ID's, but I could be missing something!</div>
<div><br>
</div>
<div>thanks,</div>
<div><br>
</div>
<div>
<div>
<div style="color:rgb(0,0,0)"><font 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 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 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>
<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 style="color:rgb(0,0,0)">Skype drfleming0227</div>
<div style="color:rgb(0,0,0)">Google-plus <a href="mailto:diane.fleming@gmail.com" target="_blank">
diane.fleming@gmail.com</a></div>
</div>
</span></div>
</div>
</div>
</div>
<div><br>
</div>
<span>
<div style="font-family:Lucida Grande;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>Matt Kassawara <<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@gmail.com</a>><br>
<span style="font-weight:bold">Date: </span>Monday, May 26, 2014 9:42 AM<br>
<span style="font-weight:bold">To: </span>Diane Fleming <<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>><br>
<span style="font-weight:bold">Cc: </span>Anne Gentle <<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>>, Andreas Jaeger <<a href="mailto:aj@suse.com" target="_blank">aj@suse.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>><br>
<span style="font-weight:bold">Subject: </span>Re: [Openstack-docs] Conventions for filenames and chapter/section IDs<br>
</div>
<div>
<div>
<div><br>
</div>
<div>
<div>
<div dir="ltr">How about describing the hierarchy in IDs, but not necessarily with ch_, section_, etc? For example:
<div><br>
</div>
<div>ch_networking -> networking</div>
<div>section_neutron-networking-ml2 -> networking-neutron-ml2</div>
<div>section_neutron-ml2-controller-node -> networking-neutron-ml2-controller-node</div>
<div><br>
</div>
<div>Also, would it help to indicate type in figure, table, and similar element IDs? For example:</div>
<div><br>
</div>
<div>example-architecture-with-legacy-networking -> fig_example-architecture-with-legacy-networking</div>
<div>table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml)<br>
</div>
<div>para3 -> par_getstart-3 (from common/ch_getstart.xml)</div>
<div><br>
</div>
<div>Or... am I still the totally crazy noob?<br>
</div>
<div><br>
</div>
<div>P.S. - I'm also interested in ideas for standardizing filenames and/or locations for figures.</div>
</div>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Sun, May 25, 2014 at 5:59 PM, Diane Fleming <span dir="ltr">
<<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.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="auto">
<div>+1 for file name conventions</div>
<div>-1 for xml:id conventions</div>
<div><br>
</div>
<div><br>
<br>
Sent from my iPhone</div>
<div>
<div>
<div><br>
On May 25, 2014, at 6:28 PM, "Anne Gentle" <<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>> wrote:<br>
<br>
</div>
<blockquote type="cite">
<div>
<div dir="ltr"><br>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Sun, May 25, 2014 at 4:50 PM, 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:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div>----- Original Message -----<br>
> From: "Anne Gentle" <<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>><br>
> To: "Andreas Jaeger" <<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>><br>
><br>
> Something to think about for ch and sec is that we won't always author in a<br>
> book-like manner, so let's not lock ourselves into that sort of thinking<br>
> due to current file names.<br>
><br>
> Stick to the install guide for now, to apply conventions, just please don't<br>
> use something as meaningful semantically as chapter and section.<br>
<br>
</div>
I actually think it's important/useful information in the filename. It reflects the root node of the file's XML which has an impact on where you can nest/include it in another document (you can't include a chapter in a section for example, but you can include
a section in a chapter). It's got more to do with the realities of the format being used than whether we're thinking in terms of books, articles, etc.<br>
</blockquote>
<div><br>
</div>
<div>I agree it's a useful codification in the file name, but I don't think we want it in the xml:id. The xml:id is used for SEO, for human-readable URLs, and so on. Let's not leak our abstraction further than we have to. :)</div>
<div>Anne</div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Granted if we moved to a non-XML format this would no longer be the case, but I think we'd have bigger conversion issues than bulk renaming the files/links. ;)<br>
<span><font color="#888888"><br>
-Steve<br>
</font></span></blockquote>
</div>
<br>
</div>
</div>
</div>
</blockquote>
</div>
</div>
<div>
<blockquote type="cite">
<div><span>_______________________________________________</span><br>
<span>Openstack-docs mailing list</span><br>
<span><a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.openstack.org</a></span><br>
<span><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></span><br>
</div>
</blockquote>
</div>
</div>
<br>
_______________________________________________<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>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</div>
</div>
</span></div>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</div></div></span>
</div>
</blockquote></div><br></div>