Re: Prototype for doc repository?

Subject: Re: Prototype for doc repository?
From: Megan Golding <mgolding -at- secureworks -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: 17 Oct 2001 10:33:35 -0400

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!



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

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 for more resources and info.

Prototype for doc repository?: From: Hart, Geoff

Previous by Author: Re: System Architecture / Documentation
Next by Author: Re: XML as Help Format
Previous by Thread: Prototype for doc repository?
Next by Thread: Not only writing skills...

What this post helpful? Share it with friends and colleagues:

Sponsored Ads