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.
Knowing what you went through on this project, I can sympathize with your
plight. You took on and completed a Herculean task with only Mickey
Mouse-like resources and support. You sir are "the Man" -- or should I
say the document database man. Just curious, what percentage of the
difficulties you encounter were tool based (i.e., BASISplus) and how much
were client or resource related? On that note, can you tell me if
BASISplus and BASISwebserver are SGML savvy?
Food for Thought:
Like you Chet, I too believe that document databases are the future of
our profession. I also believe that having the technical and managerial
skills to implement and maintain such databases will be crucial in
tomorrow's information job market. But all the skills in the world won't
mean much however if we can't convince the powers that be of the
importance of document databases. For example, I worked on a command
reference manual for software company. Maintaining this manual was
difficult to say the least. The information was constantly being updated
and changed, and the information was coming to me in variety of formats
and via a variety of delivery methods (email, hardcopy, and floppies).
Needless to say a multi-user database would have been the ideal solution
for this information need. Unfortunately, I was a mere intern at the time
and my suggestion fell on deaf ears. It seems that all too often
decisions about information management a left to those who know little or
anything about the topic and have no desire to learn about it. Instead of
asking about information management they ask about tools (i.e., what word
processor or page layout program to use). Is this a common problem in
BTW, I have a relative who works at Prentice Hall and she's getting me a
copy of your book this week. I look forward to reading it.
Last summer I didn't have much experience, but I've gotten a lot since.
give you the benefit of my learning curve, here is one concrete example
I developed a document database for a client in the semiconductor
underlying tool I used was BASISplus, and BASISwebserver from Information
Dimensions in Dublin, OH. (Web site is at www.idi.oclc.org.)
This client wanted to make information about their products available to
engineers and product designers from a password controlled portion of
public Website. They wanted to be able to list them by product family
products, Communications products, etc.) and document type (white paper,
technical manual, application note, etc.) as well as by title. They
users to be able to search the database by title, by text within the
by text within headings or subheadings, and they wanted to be able to
product family, subfamily, and/or document type. Lastly, they wanted to
to maintain the collection automatically, because this will eventually
encompass thousands of documents. (You can imagine what it would take to
maintain several toc's with thousands of entries by hand!)
We handled this by converting the documents into a modified HTML markup.
head element, we defined several non-HTML elements that the BASIS engine
use. There was dtype, pfam, psubfam, and a couple of others. So the head
element of an application note might look something like this:
(I just made that up -- I don't have any examples right at hand.)
When the document was checked into the database, BASIS would recognize
and dtype elements and put their values into appropriate fields for the
document's metadata. These were fields in a record that could be searched
the application. The document itself was checked into its own container.
In the Web pages that gave access to this document repository, we then
anchors that were search phrases rather than urls. Again, I don't
exact details, but an anchor for application notes might look something
When a reader sitting at his or her workstation clicked on "Application
the href string was sent back to the server which passed it to the BASIS
Webserver. It queried the database, build a toc of links to all records
matched the search string (all that stuff after '?') and sent them back
This was very maintainable, of course, because when a document was
the database, it instantly appeared where it belonged in all the various
And, if the client needed to reorganize the lists, we did not have to
100s of links. Much of what we needed to do could be handled by changing
search strings in the links. I did that several times.
Also, note that when I left the company, we were putting in whole tech
They were in there complete with drill down tocs and ability to filter,
well as working on a system that let clients fill out a profile, then be
notified when new documents were added to the database.
This project was not without problems, and it didn't turn out to be as
it could have, or should have, been. But none of the problems would I
assign either to the product or to the client.
BASIS has a learning curve associated with it that is steeper than most
products, but what you can do with it is truly impressive. And I firmly
that the document database -- especially where it is coupled tightly with
editorial environment -- is the future of our profession.
I hope you find this useful. Feel free to contact me if you have
Chet Ensign Office: 212-448-2466
Manager of Data Architecture Home: 201-378-3472
Matthew Bender & Company, Inc. Email: censign -at- bender -dot- com
New York, NY