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:[email protected]]
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/attachments/20111103/c4036f3a/attachment.html>
