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.
Many thanks to all of the answers to my questions about designing a
knowledgebase. Further down in this message is a summary of the suggestions
I got from this list (and a few from coworkers).
Here is some information on how I decided to design the knowledgebase:
I've decided to create a directory structure along the lines of my document
categories. The categories I have right now are: HOWTO's, Known Issues,
Architecture, Plans, and Post Mortem Reports. I plan on using revision
management software (CVS, specifically) to track submissions and changes.
Every article that is submitted will remain invisible to the web interface
until it is reviewed (per my manager). Reviewers will be notified when they
have new articles to read. When a reviewer signs off, he or she will set the
article's status to "published" which will make it visible to the intranet
users. All articles will be written in DocBook using templates I'm creating.
This minimizes the need for specialized knowledge, as I'm automating
translations to HTML and stylesheet application. We're using tags like
<pubdate> to track when an article was published, <editor> to track who
reviewed the document, and <author>. There is no separate database in my
knowledgebase -- everything is stored in text files.
It seems to me that you've got two problems here:
1) How do I structure the documentation so that people in the group can
2) How do I structure the documentation so that people outside the group
can read it?
For 1), you want to mirror as closely as possible their current
organization; for 2), you want to interview everyone else and find out
how they want to use it. These aren't necessarily contradictory, but it
might not hurt to sit down with each category of user, and find out what
they want to do with it.
(Eric the Read)
Here's an example: http://sdb.suse.de/sdb/en/html/index.html
I think I'd see if I could put together a review board. Depending on the
number of submissions, you could meet weekly or monthly or quarterly to
categorize the information. Another thing to consider would be some kind of
a peer review. We have a lot of review-type meetings here. It helps to have
more than one person to look at something, even if they aren't an expert in
that particular field. A lot of times they may have an insight that can be
very revealing. In particular, I would think that a cross-discipline look
at the drafts would help you categorize them. Some people would look for
things in different places. Hyperlinks are great and there would be no
reason not to include a document in however many categories would be
appropriate. If you start getting too many entries under one category,
start breaking it down into smaller groups.
Using a group-based hierarchy can be very friendly indeed if the divisions
between groups are clear to users; for example, everyone knows they have to
go to the Fruit site if they're looking for information on apples, and to
the Vegetable site if they're looking for information on peas. But overlaps
or ambiguities can pose serious problems in trying to find things.
Overall, the one piece of advice I would give though is to start small and
focus on one area at a time. In hindsight, I wish that I had either picked
one department to work with or picked one area of the navigation to populate
and then perfected that rather than trying to tackle the whole thing at
once. The content is getting there, but I feel like there's more breadth
than depth right now, and I think the depth would be more useful.
Getting knowledgebase articles reviewed and making sure they remain relevant
is important at my company. One suggestion I got from a coworker was to set
an expiration date on each article so that the article must be reviewed
again. The length of time from publication to expiration will vary, based on
the type of document we're dealing with. For example, "Known Issues" might
have fairly short lifetimes because we move pretty quickly on correcting
problems. A policy on how to handle a certain type of situation might have a
longer lifetime, in comparison.
(mgolding -at- secureworks -dot- net)
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com
A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/
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.