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.
Having just been through almost the exact same thing, I can attest to the fact
that it's going to take long hours but that it can happen. (I work for a a
medical devices company who wants to be able to say at a tradeshow, that begins
today, that they've submitted the 510k for a product. What they had failed to
add into their plan for the submission was a copy of the user documentation and
a copy of the test plans. The manglement only realized, and informed us, about
3-4 weeks ago that we had to write the user dox and test plans.)
Below are some things to help you get it done. But, I do want to say this: we
have a help system with our product, but do not submit the help with the 510k
submission because it's the same content as the printed guide. However, we don't
say that anywhere in our submission. We've not had the FDA come back to ask for
the online help on any submission. (Yes, we do state that there is help in the
human interface document.) Perhaps you only have to submit the guide and
possibly provide a printed list of field/button/etc. definitions for use as
1. You already have a manual. Try to use that as the single-source.
2. So that it looks complete enough to satisfy the FDA, get your manager or the
project manager to agree that you can chop up the manual to use for the
HTMLHelp. Context-sensitive help doesn't mean that you have to define every
field. You could always have a procedure or section pertinent to that window
3. If they have it already in some engineering spec, perhaps you can pull the
table of fields and definitions from the spec. It might not be the best English,
but so long as it's spelled correctly you can use it for context-sensitive help
rather than using the manual.
4. Make sure the engineering team is setting up the software so that the help
system will work. I have never worked with HTMLHelp so I'm assuming that they
can rig the software so F1 in any field brings up the specific help topic.
5. Inform the project manager that the team will have to enter the help Ids into
the code (or however that is done for HTMLHelp).
Now your work begins:
1. For the manual set up styles you like/want and use Word's search and replace
feature to search for combinations of formatting and replace them with a style.
This IS NOT the autoformat feature. (I don't trust it, but others here seem to
think it will speed up your work. It's worth a try.)
2. Get some trusted ally in the company to go through a printed version of the
guide against the electronic version to make sure the styles got applied
correctly (something that looks like a Heading 3 has a Heading 3, not 2, style
applied). That will free you up a bit if you have to work with field-level help.
3. If you can get your hands on an already-defined table of fields from the
engineering specs, convert it to topics for RoboHelp. (I am assuming you can get
this in a Word table from engineering.) While still in the table, apply the
heading style you want to the field names. Apply the body/normal style (if
necessary), to the definitions. Convert the table to text with paragraph breaks
to separate the text. At this point you probably can import the document into
RoboHelp and have it make topics using that heading style. Generate the topic
IDs/field names for engineering so they can start linking in the code.
4. After your trusted ally (or allies since it's big) has checked the guide,
make sure it's fit to print. Get that part ready. I'm assuming your FDA
submission includes a printed guide. At this point you can probably export the
manual as HTML from Word. I have no idea how good or bad it will look or what
you present to users, so this might be a big step to get it right.
5. If you can use the guide for HTMLHelp and don't have field definitions, use
the Import the guide it into RoboHelp and have it define topics based on
headings. Now your task is a little bigger, but perhaps you can get away with a
little "cheating" at this point by matching manual topics to screens rather than
specific fields. Either way (screens or fields), you will have to create a table
for engineering with the topic IDs and screens or fields to which they belong.
6. Compile and test, tweak, compile and test, tweak, compile and test, tweak.
7. Give it to engineering to run on a test system to see if it works differently
than it did on your system.
8. Tweak, compile, test, give to engineering.
technical_writer -at- rte -dot- com wrote:
> I have a new assignment: "Do a context-sensitive HTMLHelp system for
> Product X [an automated medical device used in hospital operating rooms].
> The 400-page user manual needs to be in HTML, too. We need a working
> prototype of both, complete enough to satisfy the FDA, for the next
> build on Thursday afternoon."
> * I've never done HTML Help.
> * The last version of RoboHelp I played with was v1.
> * I can't use right-clicks for context sensitivity because loading the
> Robohelp dll with the product disables many of the product features.
> * The manual has been done entirely in Normal style;
> font/size/style/justification changes for headings and captions and lists
> and stuff were all done manually for each word or paragraph.
ADAC Laboratories, Geometrics
6400 Enterprise Lane, Suite 201
Madison, WI 53719
phone: 608-298-2100, x8118
email: sschoepe -at- adacgeo -dot- com
I feel much better now that I've given up all hope...again.