A Tale of a Technical Writer who did Programming for Fun

A Tale of a Technical Writer who did Programming for Fun

V Srinivas on the TWIN list wrote:

Hello Twinners,

I must say I have been keenly following the views and opinions that have
been coming up regarding the usage of online help tools.

First of all, I would like to say that I wouldn?t want to spend much time
in ?creating? an online help file. I would rather spend time
in ?improvising? and ?thinking? about how I can make that Help file reach
the audience better. And that too, I would want to have some TIME on my
hands to do that.
I definitely wouldn?t want to spend precious time in doing work such as
copying and pasting.

>From my experiences, I can roughly put down the following statistics
relating to the thought process and labour that goes into creating manuals
and online help.

Creation of a User Manual may involve: 100% Thought Process Creation of
Online Help may involve: 10% Thought Process + 90% Labour / Mechanical Work

Which means, most of the time has been spent in copying and pasting content,
creating HTML files, building TOCs, creating indexes and so on. And
annoyingly, I was all the time aware that they are already there in the
user?s guide and that I was doing the same thing again. Sure, there are
tools in the market that can take care of the 90% labour but we are a little
wary of the price tag. Also, I have been a size fanatic. I have always
wanted my HTML files (and the resultant CHM) to be as compact as possible.
To add a few more wishes, I wanted them as ?readable? and ?editable? as
possible. In other words, I didn?t want a thousand unnecessary HTML tags to
get stuck in my document. For a live demonstration, just convert your
document to HTML using Microsoft Word So I started using RoboHelp. RoboHelp
was good ? with its good user
interfaces and other powerful features. But again, it was the same old
story. I had to still do the copying and pasting, which I loathed so much. I
still had to build a TOC (when in reality, I already have done the thinking
in structuring the TOC in Word itself) and I had to still worry about
getting the images right and stuff like that.

So, I abandoned these tools altogether and started working with the HTML
code itself. For this, I wrote small macros in Word to start tagging the
document manually. So, for about six months, I depended on two major tools:
1. MS HTML Help Workshop (for its simplicity) 2. MS Word
But I was not happy. For example, for a 75-page user?s guide, I took almost
about 3 and half-hours to convert it to online help. I will not bother to
tell you how much time I generally take for converting a 233 page user?s
guide.

Automation was the only answer. And I jumped to the occasion. For a start, I
started examining behind the scenes of a .HHP project ? how the project was
being structured, how the TOCs were structured, the indexes and so on. I had
a fair idea about the HTML part of it, because I was manually tagging the
document.

I used Microsoft Visual Basic to experiment on simply because it was so easy
to understand. One afternoon, I started playing with a Word object and
slowly but surely, my dream of automating user manuals to online help turned
into reality in the weeks to come. Some parts of it were tough and bothered
me even in my sleep but I must say, that it was a lot of fun solving one
mystery after the other. I should say, identifying and tagging the bulleted
lists and numbered lists really did bother me a lot.

BUT I DID IT!

On the afternoon of July 25th, 2003, I couldn?t help feeling a little
elated. I fed a user manual (65 pages) to my program and it took exactly 4
minutes to do all the conversions and present me the online help project on
a platter (.HHP). Another 3 seconds to compile the project and I was THROUGH!

Sure, there are still some downsides to the conversion process that I am
working on ? for example, the program is getting a little confused when it
tries to convert a table, which has merged rows/columns. Also, my program
requires that all the images should be linked to external files. I should
perhaps find a way to pick the image (linked or not) inserted in a word file
and save it to a JPEG ? now that would be something. Another downside is
that it can generate only two levels of TOC. I can in fact defend myself
saying that after the second level, it is up to us to decide whether some
content needs to be grouped into a third level and so on.

But the fact is, the program (HTML Help Express) at least gives a good kick-
start to my whole process of creating online help. It may not be the best in
the industry, but hey, it?s a solution. It can prove to be a fairly decent
in-house tool for technical writers in our company and I had a fantastic
time in developing this. And of course, I had a fantastic time in my company
explaining politely to everybody that it was a TECHNICAL WRITER who
developed the software.

So who said that Technical Writers are ?not? technical? Who says that it is
only ?they? who develop and we ?just? write? Technical Writing has been
recognized as an IT enabled service. And I feel that while we write about IT
products, we should also simultaneously use the power of IT to improve and
automate our own work processes.

Regards
V. Srinivas