DITA file naming conventions

[Roger Shuttleworth]

Hello hessiansx4

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:


* 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.
* 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.
* 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.).
* As you can see above, use underscores in file names instead of spaces. CamelCase is not a good idea, for reasons given above.

* 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.
* 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.
* 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.

* 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.
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:
             deliverable_name        
                maps
                concepts
                images
                reference
                tasks
                topics
  
  Or:
             deliverable_name
                images        
                  maps
                      concepts
                      reference
                      tasks
                      topics
  
  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.

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.

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.

Hope this helps.
Roger


Roger Shuttleworth
Technical Documentation
AV-BASE Systems Inc.
1000 Air Ontario Drive, Suite 200
London, Ontario
N5V 3S4
Tel. 519 691-0919 ext. 330
  _____  

From: hessiansx4 [mailto:hessiansx4 at yahoo.com]
To: framers at lists.frameusers.com [mailto:framers at lists.frameusers.com]
Sent: Thu, 03 Nov 2011 02:49:05 -0400
Subject: DITA file naming conventions



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!  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.frameusers.com/pipermail/framers-frameusers.com/attachments/20111103/c4036f3a/attachment.htm>