<div dir="ltr">Here's what I'll update in the Documentation/Conventions page if everyone agrees:<br><div><br></div><div>For file names, use bk_ ch_ and sec_ at the beginning of the file name to indicate the type of file it is in the hierarchy of the build. For further organization, you can use subdirectories to organize the files by a particular grouping such as project or topic.</div>

<div><br></div><div>For xml:id creation, follow these guidelines. </div><div> - xml:id must be unique across a built deliverable, otherwise you get build errors</div><div> - xml:id creates the HTML file name so it should be human-readable, not codified like the file name</div>

<div> - xml:id should closely follow the actual title in the text, using dashes for spaces</div><div> - xml:id creation should consider search and find-ability as well as human-readability</div><div><br></div><div>I prefer not to document the use a processing instruction like <?dbhtml filename="name"> as that should be the rare exception.</div>

<div><br></div><div>Thanks,</div><div>Anne</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, May 26, 2014 at 11:13 AM, Nick Chase <span dir="ltr"><<a href="mailto:nchase@mirantis.com" target="_blank">nchase@mirantis.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">My concern on this is that it raises a barrier to entry for contributors.  It's not intuitive.  As a fix in an emergency, sure.  But I'd be concerned about building this out as the standard way we do things.<span class="HOEnZb"><font color="#888888"><div>


<br></div><div>----  Nick</div></font></span></div><div class="HOEnZb"><div class="h5"><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, May 26, 2014 at 11:43 AM, David Cramer <span dir="ltr"><<a href="mailto:david.cramer@rackspace.com" target="_blank">david.cramer@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>On 5/26/14, 10:07 AM, Nick Chase wrote:<br>
> Plus my concern in changing Id values is breaking any references.<br>
<br>
</div>You can reduce (but not eliminate) the impact of a file name change by<br>
changing the file names via a processing instruction:<br>
<br>
<section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>...<br>
<br>
If you use <?dbhtml filename="..."?> you'll get the aesthetically<br>
pleasing intro.html file name without having to change the xml:id and<br>
break xrefs to the section. However, if you have external links to<br>
some-dumb-id.html from other documents, those links would obviously break.<br>
<br>
Regardless of the publishing tool chain, when changing the names of<br>
existing resources on the web, the best approach is to add 301 redirects<br>
to avoid breaking bookmarks, links, and losing SEO karma.<br>
<br>
Regards,<br>
David<br>
<br>
</blockquote></div><br></div>
</div></div><br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">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>