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.
Mike W. reports: <<In designing a documentation repository, I have been
asked to create a File Naming Convention, as well as a File Tree. I have
done some research regarding these topics, but have not come up with much.
Does anyone here have some experience with these topics and how they work?>>
The trick is to accomplish two goals: First, create a structure that
parallels how users will seek files, and ideally keep the structure as
shallow as possible; there's nothing more annoying than having to repeatedly
dig 20 levels deep in a hierarchy as part of your daily chores. Second,
rather than relying on a rigid and consistent numbering or coding scheme,
create directory names that are mnemonic and that tell readers the full name
and purpose of a document by the time they reach the end of the hierarchy
and find the file. The problem* with using non-mnemonic numbering schemes is
that they're easy to muck up, and someone has to remember to keep an index
of which number relates to which document current and accurate, which is not
trivial. The problem with the name-based approach is that you have to be
able to identify clear, distinct names for each level in the hierarchy. If
the categories are fuzzy, then the names are inevitably fuzzy, and it
becomes difficult to consistently place documents in the right directory.
Think, for example, of the difference between directories labeled "safety"
and "security": the distinction is clear to a word geek, but not necessarily
to the average reader looking for files in a hurry.
* Of course, if the daily work of the users of this repository revolves
around clearly defined numbering schemes that everyone understands and has
memorized, the numbering scheme may actually be a better system for
organizing the documents. Think of a repository of commentaries on a body of
legislation, for example; lawyers using the repository will probably think
first of the statute number and subsection.
By way of example, consider an application in which I'm creating a
bibliography of reports for each of my authors. My primary goal will be to
easily find all reports that a given author produced in a given year. An
efficient structure might be [drive]/[year]/[author]: the hierarchy is
shallow (three levels), and lets me gather everything published by that
author in a specific year simply by copying the [author] subdirectory.
Conversely, if my goal was to easily find all an author's publications,
irrespective of year, [drive]/[author]/[year] might make more sense; again,
I simply copy the [author] directory and all subdirectories. If your
operating system lets you use aliases or shortcuts to directories (most now
do), you can accomplish both goals simply and elegantly: create the first of
my two examples as the actual physical directory structure, and create a
nested series of shortcuts/aliases that emulates the second structure. This
is particularly easy to do if you create an HTML front-end to the
repository: you can create as many "table of contents" pages as there are
users, and particularly so if you use a query-based main page.
--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.
For details and online registration, visit http://ieeepcs.org/2001
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
