Re: I need HELP documenting customizable software, too

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

At 10:08 AM 2/1/96, Sigrid A. Schoepel wrote:
>David Castro asked for helpful hints and advice for documenting his
>company's customizable software. I feel for him. My company is changing
>from a character-based (DOS) user interface to a Windows-based user
>interface. Along with the move to Windows, the customer is going to be
>able to change the field names ("Job" Id to "Project" Id) in the software.


>The company president wants world-class documentation. We are looking at
>CD-ROM, online help, paper, and possibly the Internet for ways of
>distributing the documentation. There is no plan for any of these, but the
>company is looking at creating a Mac version, selling the software
>internationally (translation concerns), and either providing customized
>documentation or allowing the customer to customize the documentation.

Seems to me like you've got two major tasks ahead of you...
Documenting the ways in which the software can be customized,
and how to do it, for the middle-guy -- and providing skeletal
documentation that can be customized for the end-user.

That said, I'll try to answer *some* of your questions (tho I
don't have answers to all of them).


>Documenting the character-based software was sporadic and the information
>is very out-of-date except for release notes.

>Questions:
>Can you/how do you create online help for Windows that will work on the Mac?

I don't know of any specific tools. This is going to take some
research. Bear in mind, though, as you search... The industry
asked and the users answered -- users prefer cross-platform
software to conform to the *platform* on which they're using it --
not to function identically across platforms -- so don't look for
software that will imitate Windows help on the Mac, look for a
way to translate the help text to a Mac-centric help format.


>What issues should the president/programmers/writers be aware of when
>translating the software and the documentation?

Translating is expensive -- in money, time, and space (screen real
estate and paper). Most languages take up a lot more room than
English does, so plan ahead.

For docs, that'll mean larger books and larger help files in the
other languages, so plan ahead. If you're working toward a simultaneous
release (hard to do, I've heard <g> ), buy asprin in bulk and place
cots in the corridor, 'cause you'll need them.

For programmers... There's a way to design programs so that most/
all screen text, error messages, etc. are stored together rather
than disparately throughout the system.  They'll need to investigate
this. Also, they'll need to leave plenty of white space in dialog
boxes, etc., to allow for the extra room the target language will
take up.

The company president better make sure the company has the resources
to commit to this effort, chip in on the asprin, and forget about
sending the kids to college or vacationing in Bermuda until it's
all over.  ;-)


>Are there ways to distribute and update documentation to which a customer
>has made changes? What is the best method? Is it better to give them the
>software documentation and let them create separate company-specific
>documents?

>Are there programs/ways to let customers change online help?

Presumably, the procedures that middle-guy will need to customize
the software will not change, so you can finalize them.

The software should have a non-flexible core functionality that
won't change. This can be the skeleton for the docs that you
can give to middle-guy to customize. Areas where the program
functionality or field names can change could be represented in
template format. Special characters or styles can mark places
that'll change, and, if you make it something "searchable", so
much the better.

Since middle-guy can't change the words on a printed page, you'll
have to trust them with soft copy <cringe>. Likewise, you'll have
to give them uncompiled help (.rtf format), so they can make their
changes before they compile.


>The software is a large accounting/project management package with
>multiple audiences. How do you determine what audience/level to write to
>when many types of people will be using the same module/part of the
>software?

Sounds like a job for progressive disclosure! Think of it as "help me,
help me more, help me more than that" documentation -- provide overviews,
then go into more specific details. You can structure your documents
and online help to present different levels of information consistently,
with lots of visual cues, so that users can find their own levels easily.

For example, in the help file, context sensitive access can give
a brief overview of fields. Hyperlinks can take you into more and
more specific information, background information, etc. In the
paper docs, you may want to begin each chapter/section with a
clearly labeled overview. More detail can follow in the body of
the chapter. Background info can (for example) always be on a left
(even) page in a box with a 20% grey background. Just be consistent
and explain what you've done in a preface or intro.

Good luck! Hope it turns out to be the project of a lifetime
rather than the project from hell!!!


-Sue Gallagher
sgallagher -at- expersoft -dot- com