Review: Tools for a new doc environment

[Shawn Brown-Knoernschild <sbk -at- PENTATECHINC -dot- COM>]

I have received requests from some of you for a review of the information I received from my posting last week. The truth is that I received more requests for reviews than actual responses to my query. I'll reprint my original question along with parts of the responses I received. Thank you to everyone who offered input.



At my company, we are in the process of drafting a plan for a future documentation environment. We are a small software company with one product that is updated quarterly. With so many releases, we are having problems keeping documents cohesive and organized. We support an ORACLE database containing about 1,000 tables, and we want to develop a central repository of descriptive text about each data element.

I'm posting to the list because we want to locate a tool (we are currently working with Word and Robohelp) that will permit us to get the maximum re-use of the data descriptions. For instance, we would like to be able to merge raw text without the data descriptions with something containing the data descriptions and achieve a final text (such as a traditional paper manual) that shares the same descriptions as the online, context-sensitive help. We want to produce paper docs while building toward a future where our customers can download documentation from the Internet.

Does anyone know of software programs that can fulfill the following criteria?
1.  Online and paper documents written and edited from a single source.
2.  Online help easily updated.
3.  Object-oriented.
4.  User-definable online help is not affected (erased) by system upgrades.

If you have any suggestions or information leading to suggestions, please respond to me directly. Thank you in advance.

Shawn Brown-Knoernschild
sbk -at- pentatechinc -dot- com
Penta Technologies, Inc.

Views expressed are mine, not necessarily Penta's.



Jill Burgchardt wrote:

We use Forehelp on a Windows 95 environment.  Forehelp is a database, so we can output in several formats--rtfs, winhelp, html, and to Word.  Our main application runs on UNIX systems, so we compile the rtfs with Hyperhelp on the Unix platform.

The rtfs and compiled winhelp are the cleanest.  The html is okay, but requires some tweaking to cleanup a few odd items.  For Word, it pulls topics in order specified (must be input) and converts styles per specification.  This is fairly cumbersome to set up (we have over 2400 topics).  Also, I don't always want topics to have hierarchy in Word that corresponds to the winhelp style conversion.   So, content is okay, still have clean up.

User-definable online help (annotations and bookmarks, I'm guessing) are lost on upgrade.  We send release notes to our system administrators instructing them on how to save the annotations file before upgrade, so that information can be copied to the new release.  Bookmarks they must re-establish. That's the best we've been able to come up with so far. I believe this is a help limitation that is true regardless of the tool used.


Gershonl Joseph wrote:

I am about to start a Word 97 vs FrameMaker 5.5 investigation. We currently use Word 6 and 7 and, following preliminary investigations, have found that there are only two contenders for our Win95/NT environment.
We have also considered using Word and Excel to manage our docs. In Office 97, one can store pieces of Word documents in Excel database records. One then writes a procedure to build your final printed or online doc, assigning a different style sheet (template) to each one as needed. This also allows you to make customer-specific manuals for a customer who does not order every feature of the system.
We will be using Word or FrameMaker for our online and printed docs. Online help will be developed separately, as it is integrated with the application. We are hoping that it will be possible to generate the first draft of the online help from the online/printed doc files.


J Warnick wrote:

I've used Doc-To-Help for four years.  The application works inside Microsoft Word.  I've converted the safety manuals and other process safety management manuals of several large oil companies to help files
using this tool.  Go to http://www.wextech.com and check it out. (usual disclaimer, a satisfied customer only)

Look at their documentation suite.  When I click "Make-Into-Help," I can choose to generate both html and help files. On my current project, I am keeping the company's forms and other changeable data in Word format. Calls are made to the WordViewer (free from Microsoft) from the help files. This allows users to read and/or print the forms at remote locations, as well as allowing the company to easily make changes to certain data without having to recompile the help files.  I am also using Helpsite (part of the suite) to generate html files at the same time as the help files are created.


Scott Miller wrote:

I don't know of any tool that would satisfy all of your requirements. Many companies who have very specific needs write their own authoring system. I used to work at Lotus where we had a Notes-based system, where you authored in Ami Pro, and used a Notes database to store your text. It worked very well. I've heard of similar things done by Borland. There are pros and cons of developing your own authoring environment, but it can be a good way to go, if you have the resources to implement it. Since you already deal with an Oracle database, maybe you could write something to take advantage of that.

As for off-the-shelf help authoring tools, your best bet might be one of the database-oriented tools such as Forehelp or HDK.




Everyone please feel free to add to these suggestions. I know individuals at my company would appreciate it. Thanks.

Shawn Brown-Knoernschild

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html