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: Opinions on Embedded Help From:Gwen Thomas <thomasgp -at- CBS -dot- FISERV -dot- COM> Date:Wed, 10 Mar 1999 10:52:50 -0500
Opinion: Great thread! This kind of interchange is so valuable...
Matthew Stern wrote:
<Embedded help does require programmer support, perhaps *a lot* of programmer
support depending on how you want to implement it. You'll need to fit in
time to do the coding and testing.>
My 2 cents:
Embedded help doesn't have to be too difficult, time-consuming, or require a lot of support, under the right circumstances.
An international credit card software company I worked for developed a GUI version of their product, which in the past had been green-screen only, with no help. Not only did the marketing guys want field-level help (about 3000 fields) for the product, they wanted it to be obvious they had it, always visible, nicely formatted, and they wanted it in the appropriate language of the user. AND they wanted very little writer time and virtually no development time.
They came to me after they'd placed an RTF control box on the GUI to hold the help and had realized how long it would take to type in 3000 field descriptions that would be updated quarterly. (If I remember correctly, the control was tied to the field with the focus.) I already had field descriptions stored in ASCII format in an Access database. I created a Word template as a mailmerge catalog and inserted RTF coding (if you can do HTML, RTF is a breeze) surrounding Word mailmerge fields for the various parts of the help. We generated the catalog and saved it as a text file, which the developers inserted into the middle of the file containing the coding that the application required for the control.
The end user could read the help or actually edit it, adding their own enterprise-specific comments as needed.
When the doc database changed, we could regenerate the application help in about 5 minutes. (No, we hadn't got around to the process of saving the end-user's "notes" when I left.) And, when the developers later decided they needed help worded differently from the print/PDF field descriptions, two of us simply copied the "columns" in the database, made a lot of global changes and a few tweaks, and got the job done in a day or two.
For non-English help, they translated the database, which represented a very large cost savings over traditional methods.
The developers and I probably spent 40-50 hours getting the bugs out of the process (a lot of systematic experimenting to see where the RTF coding was butting heads with the application coding). The last I heard, the process itself is solid. Kind of low-tech, compared to a traditional help system, but it filled the ticket, and it got good response in product demos.
Nice by-product: the doc group solved a problem that had stumped the COBOL and C++ developers. The project lead, with whom I had a great relationship (we mentored each other on various topics) gave us credit to everyone from the project manager to the CEO. It was very good for the department.
