<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN'>
<html><head><meta http-equiv="Content-Type" content="text/html;charset=us-ascii">
<style>BODY{font:10pt Tahoma, Verdana, sans-serif}</style></head><body>
Hello hessiansx4<br><br>Join the dita-users group on Yahoo and search in the archives there. You'll find lots of good advice from people who know a heck of a lot more about XML than I do. But I can tell you what I have gleaned from various user groups:<br><ol><li>Use only lower-case lettering for both files and folders. Why? XML is case-sensitive, so you don't want authors to stumble over which case to use for href attribute values, for example. It's the KISS principle.</li><li>Remember also that, since XML is all about interchangeability, and your content may end up in a Linux or Unix environment, you should avoid all special characters except for underscores in file and folder names. That includes periods and spaces: ban them in folder and file names.</li><li>As far as possible, make sure the file name matches the title of the topic. So if your topic is "Inserting the Widget" then your file name would be "inserting_the_widget.xml". I realize this may cause problems later if the title changes, but that doesn't happen often and you can usually make the change to the file name without too much hassle (changing it in ditamaps, etc.).</li><li>As you can see above, use underscores in file names instead of spaces. CamelCase is not a good idea, for reasons given above.<br></li><li>We add a suffix to the file name to indicate the topic type: inserting_the_widget_c.xml is a concept; _t for a task; _r for a reference; _tp for a topic (rarely used). That makes it easier to locate the file in a concepts folder, for example.</li><li>If you use XML and DITA, you will find yourself working with large numbers of topic files. This may sound intimidating, but with good folder structure it is not a problem.</li><li>For ditamaps, make full use of the nesting capabilities (that is, a map referencing a map) so that your maps don't get too large. It is easier to handle a map that has five sub-maps than to handle one map containing hundreds of topics.<br></li><li value="6">Don't assume that these rules are irrelevant if you're not planning on using XML right now. There's great benefit in using structured authoring and DITA even without going so far as to use XML, but you probably will want to take that step in the future. Don't paint yourself into a corner.</li></ol>As regards folder structure, opinions vary. Most people
recommend keeping ditamaps in a maps folder, and topics in three or four
sibling folders (concepts, topics, reference, tasks). Some people just
have a topics folder and keep all topic types together; that may work if your numbers are relatively small. It is good
practice to keep relative paths simple (for example, for href attributes). So organize your folders in a shallow structure; something like:<br>
deliverable_name <br>
maps<br>
concepts<br>
images<br>
reference<br>
tasks<br>
topics<br>
<br>
Or:<br>
deliverable_name<br>
images <br>
maps<br>
concepts<br>
reference<br>
tasks<br>
topics<br>
<br>
That way, your relative paths from map to topic are simple, and from topic to image. What you don't want are long ../../../../ strings in the hrefs. Since you will be using FM, your maps folder will eventually contain other things apart from maps.<br><br>One last thing: Take a look at DITA-FMx from leximation.com. It simplifies things a lot. If you're making the switch in the near future, don't buy DITA-FMx until the new version comes out in a few months.<br><br>In our experience, you can manage many hundreds of files without needing an expensive content management system. Get used to working with XML first before even thinking about a CMS.<br><br>Hope this helps.<br>Roger<br><br><br>Roger Shuttleworth<br>Technical Documentation<br>AV-BASE Systems Inc.<br>1000 Air Ontario Drive, Suite 200<br>London, Ontario<br>N5V 3S4<br>Tel. 519 691-0919 ext. 330<br><blockquote style="padding-left: 5px; margin-left: 5px; border-left: #0000ff 2px solid; margin-right: 0px"><hr><b>From:</b> hessiansx4 [mailto:hessiansx4@yahoo.com]<br><b>To:</b> framers@lists.frameusers.com [mailto:framers@lists.frameusers.com]<br><b>Sent:</b> Thu, 03 Nov 2011 02:49:05 -0400<br><b>Subject:</b> DITA file naming conventions<br><br><div style="color:#000; background-color:#fff; font-family:verdana, helvetica, sans-serif;font-size:10pt"><div style="RIGHT: auto">Hello All! My company is in the process of transitioning from FM8 unstructured > FM10 DITA and are discussing file naming conventions. Have any of you had a similar experience (transitioning to DITA)? Any caveats you want to share about the process (what worked/what didn't)? How about file naming conventions? Any and all suggestions are welcomed!</div></div></blockquote><style>
</style>
</body></html>