TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
My company is investigating DITA/structured writing for documentation
and eLearning. We are creating the standards (what DITA types and
components do we want to use, what metadata do we want to collect,
file/folder structure, etc.). We've broken the initial phase into three
My team is looking at the folder structure and file naming conventions.
I think that there are three ways to go.
1. Hierarchical folder structure like Customer\Product\DITA Type (e.g.,
2. Flat folder structure with file naming conventions (e.g.,
t_widget_opening.xml, where t represents a task, etc.)
3. Unstructured folders and file names not following specific
structures. For this we would need a database, enter the relevant
information (file location, file name, various metadata, etc.) in the
We see advantages and disadvantages with each, and it may depend on the
tools that are being used. If the customer or product name changes (as
they do from time to time), how do you handle that with #1 or #2? How
can you handle changing the folder names when they are in conrefs? How
likely is it that authors will remember the naming convention or want to
enter a lot of data in a database?
We're looking at using Oxygen, Framemaker, XMetal, or AuthorIT for the
authoring. For a CMS, the company has SharePoint (we haven't actually
implemented it yet) and we will use this initially, but we may be able
to look into other CMSs depending on cost and functionality.
So, my questions (at last!!!)...what folder structure and tools did/do
you use? What are the problems that you've run into using that
structure? I don't want to start a tool war, but if the tool has
problems, how have you worked around those problems?
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-