Re: Is It My Job? (long, sorry!)

["Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM>]

Moshe Koenig wrote:
>I'd like some referees on a situation that I have faced on a project
>that doesn't seem to want to die. Somehow I feel that I'm being
>stuck with a job that not only isn't mine but that shouldn't be.

[snip some background]
>After I prepared my initial online Help project, the programmers
>told me that they could not work with my context strings; they
>provided me with a file with the context strings and numbers
>that they wanted to use. I aliased the entire project to make
>their strings take priority. Then I got my next surprise: they
>told me that my Help was "worthless" because I needed to provide
>documentation on every menu option so that a user choosing a
>menu option could press F1 and get a description of the command
>the option launched.

>To my way of thinking, doing this makes no sense; [snip]
> I decided that the sanest solution was to do a
>screen capture of the menu and to create popups for each option (the
>project is for a Win 3.11 application). I then aliased the topics
>with the segmented menus. To my utter astonishment, the developers
>rejected my solution outright! They gave me back a map file with their
>strings and numbers and comments regarding what they regarded as my
>own lack of professionality!

Ok, Moshe, let's handle Win 3.1 help issues first...

Different programming languages call online help in different ways.
So, while I certainly don't agree with their methods, I can understand
the programmers asking you to change the context strings. Aliasing
their context strings to yours was the reasonable thing to do.

Early context-sensitive help files *did* have topics attached to
each menu item. We'd open up a full blown help window just to say,
"Opens a dialog that allows you to save the file with a different
name or in a different location". By 1994 or so, nobody was doing
this anymore. Word 6 was the first app (that I can remember, anyway)
to attach menu item help to the dialog box help topic, so when you
hit F1 from the File>Save As option, you got help for the Save As
dialog.

Many applications, some of the ones that I documented included, segued
to overall help for the main window in which a segmented graphic explained
all the elements of the program's main window, including menus, just as
yours did. There ain't nuthin' wrong with that approach. It closely
mimicks the "What's this?" help of Win 95, so could be defended as the
most logical way to ensure forward compatibility.

In Win 95, there's "What's this?" help, so some menu items are again being
documented. However, in Word 7, not all menu items have help. Tools >
Grammar has a help topic, but File > Save As does not. Don't ask me how
they decided what got help and what didn't. Idunno.

In any case, there is justification, and precedent, for Windows 3.1
help to go any of the three ways--to individual help topics, to the
dialog box that the menu item calls, or to a single "main window"
help topic.


>I really can't say to what extent technical writers work with
>developers when it comes to making context sensitive Help, but it
>seems to me that the technical writer has to close out matters of
>design with the project manager, not with the developers, who then
>request redundancy that serves only to inflate the Help file, which
>is already rivaling the software itself for disk space required.
>Most of the technical writers I know only prepare standalone Help
>and, at the most, include aliases, but it doesn't go as far as I've
>been asked to go.

>Where do I draw the line? Is this my job?


When I created my first help file, I ended up entering the help hooks
into the code myself because nobody else had time to do it. It wasn't
my job, but I wanted the product to have online help. I often look
back on that and think of how far we've come. ;-) And no, I don't think
that programming the help hooks should be your job. However, many
help developers do test their own help and perform other tasks that
are not strictly writing because many companies are ill-prepared
to deal with help issues.

But, I do think that you could have avoided a lot of the problems
you described if you had started off the job on the right foot --
by creating a detailed doc plan that included a plan for the online
help.

Your online help plan should include:

        For context-sensitive help:
        which controls and which dialog boxes will be included
        and/or excluded from the help (so, for example, you could
        state that c/s help would not be attached to menu items).

        How c/s help will be accessed (for example available by
        pressing F1 but not availble by browsing the help file or
        via the search engine).

        Who will determine context strings and when you need them
        or when you will provide programming with them.

        For procedural help:
        which procedures will be placed online and which will
        remain paper-based.

        How procedural help will be accessed (for example available
        via links from c/s help, via the search engine, and by
        browsing from the contents page).

        For conceptual help, pretty much the same info as procedural.

        For definitions, whether pop-ups will be enough or you need
        a full-blown glossary.

        For the help file in general, what application (or set of
        applications) will be used as a model or standard (to help
        settle arguments like the menu thing), and who will arbitrate
        disputes. You may also want to put things about choice of
        fonts and colors and the like in the plan, too.

I know this advice comes too late for your current project, Moshe. But
never underestimate the value of a doc plan. The lack of one *will* come
back to haunt you.

Sue Gallagher
sgallagher -at- expersoft -dot- com
     -- The _Guide_ is definitive.
        Reality is frequently inaccurate.

                  TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send administrative commands
         ALL other questions or problems concerning the list
       should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-