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.
Subject:Re: Designing a Knowledgebase From:aschiff -at- factset -dot- com To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 30 Mar 2001 12:09:46 -0500
Megan Golding is
<<designing a company-wide (technical) knowledgebase and am looking for
some tips from Techwr-l. I work with several technical groups -- including
developers, systems administrators, field engineers, and technical
Congratulations - this sounds like a challenging & potentially very useful
<<In particular, I need a scheme for organization of the documents that
the knowledgebase. I've thought about segregating documents by authoring
group (development, systems administrators, etc.) but don't think this is
very user-friendly. I'm picturing allowing users to "browse" the
knowledgebase like they browse Yahoo -- by category.>>
I think you're on the right track here: Organize the knowledgebase by task
category, so end-users can find what they need fairly quickly. (The only
way to figure out what the categories should be is to talk to your
end-users -- maybe convene an advisory panel, and/or shadow a few end-users
for a day and see what kinds of reference information they're looking up.)
Then, categorize as best you can.
HOWEVER, I strongly recommend providing users with a robust full-text
search capability as well (that's what I end up using 99% of the time on
Yahoo anyway.) Without getting into the "why's": In my experience,
end-users prefer to access reference/help information in the following
2.full-text search (the more powerful/flexible, the better)
3.drilling down through categories
So - if you have a limited amount of time & resources to spend on this
project, I'd recommend focusing more energy on #1 and/or #2 than #3.
<<Also, a group of about 10 people will be contributing information to this
knowledgebase. I don't want to have to edit and publish their stuff --
folks should be able to publish themselves. How would you manage this? One
issue is quality: how can I enforce quality on the knowledgebase articles?
was thinking of managing contributors by creating a category called
and allowing contributors other than myself to publish only to that
category. This section would include visual cues that the topic(s) is/are
draft-quality, but still allow the information to be searched for, found,
and used. I can review the contents of the "drafts" category regularly and
publish this info to the appropriate final category.>>
Wow - this is a big question. No one answer fits every
organization/tech.writing dept; it all depends on a lot of different
factors, including how much time you have to manage this project on an
At my company, we had an *internal* Lotus Notes Knowledgebase for several
years. I wasn't around when it was set up, but anyone could create & amend
documents, and "Draft" & "Final" designations were available. When you
created something, it was in DRAFT format, and a VERY select group of
people at the company (two, to be exact) could upgrade a document from
DRAFT to FINAL. Anyone within the company could see both draft and final
documents, either in separate Notes views or -- much more commonly --
together in an "All Documents" view.
To make a long anecdote longer, the 2 people who had authorization to
upgrade docs from DRAFT to FINAL had other projects & responsibilities, and
with no real project manager or leadership on the Kbase project, their
Kbase responsibilities fell by the wayside. People at the company were
still creating Kbase documents, but they were forever Drafts. No biggie in
the short-term, but years later (late 90's) the Kbase had almost 2,000
documents in it -- some new, some old, some horribly out-of-date (even
This presented several BIG problems:
* No way to tell what was correct/up-to-date and what was
* No unified voice or context for information (many different authors, many
different styles, etc. etc. -- you can imagine...)
* Our help-desk staff relied heavily on the Kbase for answering client
questions, and frequently printed out & faxed documents to clients (how
antiquated, in the Web-world!)
* Consequently, we were getting pressure from the Help Desk to publish the
Kbase on the web (Lotus Notes lets you do this). But by this point
"cleaning up the Kbase" was a colossal project and no one had the time or
In short, a mess.
I won't get into how we solved this problem, but the moral of the story is:
Decide beforehand on the Business Rules that will govern this endeavor, and
make sure everyone involved is on the same page. Every solution has its
inherent benefits & drawbacks, but it's really important to find a solution
that not only works for you & your audience _now_, but also going forward.
A Knowledgebase is a living, breathing project... it never "gets finished"
in the traditional sense.
Good luck & keep us posted on the success of your project! (and, if anyone
is interested in Part II of the above anecdote, "The Solution," let me
*** 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.