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.
On Wed, 2001-10-17 at 09:38, Hart, Geoff wrote:
> The best starting point is with the people who will use the repository,
> since whatever you design must meet their needs first and foremost.
Yes! Gathering user requirements is the best first step you can take. In
my case, I had similar doc repository needs. I interviewed random
customers in my company (this was to be a company-wide knowledgebase)
and incorporated their feedback into my design.
> Don't forget that any kind of online repository inevitably grows, and
> this
> means you'll have to allow for growth. Talk to the people who will be
> generating content for this repository (both users and managers) to find
> out
> what they think might conceivably become part of the repository in
> future--even if it's a seemingly silly idea and has a low probability of
> ever occurring.
I would suggest a repository that can handle documents of any format. I
initially designed for text files only (HTML being the primary format)
but wound up needing to incorporate PDF files. My design was constrained
by my early decision to support text files.
At its most basic level, a doc repository can consist of the following:
1. A web server. I've piggybacked on our corporate intranet.
2. A structure into which to present the docs to the user.
3. A search tool. I'm using HTDig, an open source HTML search engine.
4. A good index, as Geoff suggested.
5. A means of publishing. I allow other people to publish to our
repository so that I'm not a bottleneck in the publishing process.
6. Depending on your needs, you'll probably want revision history and
version control. Both are rolled into one with CVS in my config. If
you're on a Windows platform, investigate VSS from Microsoft.
In her book, _Developing Quality Techincal Information_, Gretchen Hargis
proposes nine characteristics for quality technical information. Of
these, I would propose that Organization and Retrievability apply
equally well to a documentation repository. A search engine and index
will assist in Retrievability. Meanwhile, the presentation structure
will assist in Organization.
Good luck!
Meg
--
Megan Golding (mgolding -at- secureworks -dot- net)
SecureWorks, Inc.
Don't worry about the world coming to an end today.
It's already tomorrow in Australia.
-- Charles M. Schulz
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
