SUMMARY: Designing a new help system

Subject: SUMMARY: Designing a new help system
From: "Rene Stephenson" <RStephenson -at- mwci -dot- mea -dot- com>
To: techwr-l
Date: Tue, 7 Dec 1999 6:57:21

The topics posed:
1. Screen shots -- good or evil?
2. Internationalization considerations
3. Reviews for online help
4. Project schedule for developmental software

The strongest responses have been to the screen shot debate. I hope

you find useful the following summary of replies. Ellipsis (...)

indicates my omission. I have numbered the responses according to the

topics listed above.

Sue Ahrenhold [sahrenho -at- arbortext -dot- com] writes:

1. I find screen captures to be problematic in online help. What

looks good in the Windows environment suddenly looks over-large in a

help window. Shrinking the grahic often results in a loss of quality

so severe that the user can't tell what the screen capture

represents. The only graphics I like in online help are little ones,

like toolbar buttons or icons.


Justin Cascio <Justin_Cascio -at- tvratings -dot- com> writes:

1. I'd lean on the developers to name those screens, and avoid screen

shots. If the help's context-sensitive, it's redundant, and replacing

the shots is another internationalization issue.


"Kathi Jan Knill" <Kathi -dot- Knill -at- template -dot- com> writes:

1. Screen shots, good or evil --
I think they are evil! If the user is accessing help, he is already

at the screen he needs to know about. It can be more confusing if

even one tiny detail is changed between what he sees and what is in

the screen shot... I have created many help systems where I had the

pop-up definitions come from the word on the page for the help


2. Internationalization --
Watch the spacing and sizing of menus...

4. Project Schedule -- ...start with whereever the developers are at

the point in time that you are ready to begin planning. You should

know the features and functions of the system at that point. So you

estimate how long it will take you to do that part. Then you just add

in time factors for how many other features or functions the finished

system will have. (Hopefully someone has specs or at least knows what

the finished product is supposed to be.)

"Donna Marino" <domarino -at- earthlink -dot- net> writes:

1. Screen shots are really intended for printed documentation, not

online help...including it in the online help is just redundant and

confusing. Also, ...makes internationalization a nightmare. Keep the

help simple and avoid using graphics; it will make the translation

process much easier.


"Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM> writes:

1. I'm wondering if anyone else has found issues with NOT providing

screen shots in on-line documentation. I did a fairly informal test

... The consensus...was that they like screen shots, because it

helped them figure out if they were in the right place by comparing.

We came to the conclusion that screen shots were essential ...We're

looking ways to make [the screen shot] glaringly obvious too...I give

it the torn edge look, and break it out by grouped functions.

4. soon as I know the general functional design as been
approved, then I can at least determine a sense of direction. I work

with development builds and document as the functions become



John Posada <jposada01 -at- yahoo -dot- com> writes:

1. I have a screen shot in every help window...because I've also

defined each field and button in the image as a hotspot... It is

easier than listing each field and the explaination on the page...I

understand about context sentive, the downside is
that the developer would have to input over 1,000 map
id numbers and on the real estate issue, because this
application is used to view scanned documents,
everyone is using at minimum, 21" monitors, some
larger, with HUGE disks...


Jim Shaeffer <jims -at- spsi -dot- com> writes:

1. To generalize: People like screen shots. Help developers hate

screen shots. Actually, I like to create screenshots with hot links

to explanations (as John Posada describes). Marketing also thinks

they are cool when giving demos of the product and its help. What I

hate is needing to recreate all those shots every time some developer

changes the graphic design used in a button or other widget. Changing

a text list is easier and faster.


Ginger Moskowitz <ginger -at- aatech -dot- com> writes:

2. Consider word length... Try to cut out excess words.


"Donna Marino" <domarino -at- earthlink -dot- net> writes:

1. ...Listen to your users. If they want to see screens in online

help, I would provide them. Every audience is different.


"Michelle Wolfe" <WOLFEM -at- bcbsil -dot- com> writes:

4. ...I have found that usually the developers have a test plan,

maybe with cycles defined containing tests for specific

functionality. I use those test plans as a starting point...That way,

I am only one cycle behind the development. The later test cycles

often test interoperability between systems and that gives me the

time to complete writing and testing the help...


Darren Barefoot <dbarefoot -at- mpsbc -dot- com> writes:

1. ...[W]e're planning on using [screen shots] where appropriate...

We're exploring using some sort of visual key--a border or label or

something--that clearly indicates what the screen shot is. I have

read that users may sometimes get mixed up between the images within

a help system and the interface itself. We aim to try to avoid this.


Anne Magee <magee -at- universal -dot- ca> writes:

1. ...Some people like the screen shots because it reassures them

that they are in the right place, others find them annoying. My

problem with them was that they were usually much to big to fit in

the help window, which I try to keep as small as possible. I

compromised by putting all screen shots except very tiny ones in pop


2. ...If internationalization becomes a problem, the shots can

(relatively) easily be removed by removing the links to the pop up



Jo Francis Byrd <jbyrd -at- byrdwrites -dot- com> writes:

1. When I need to define the fields, I define a separate window for

the graphic and provide a link to it. That way, if the user

wants/needs to know about a field or menu option, they can go to it.

Otherwise, they can ignore it and not clutter up the real estate.


Paul Hanson <PHanson -at- Quintrex -dot- com> writes:

1. First of all, I *like* screen shots in help files...based on .shg

graphics. In the future, though, we are going to use them sparingly,

if at all. ...There is not enough time or manpower to be checking and

re-checking the GUI hasn't changed...


Mitchell Gibbs <gibbs -at- gnv -dot- fdt -dot- net> writes:

1. I use screenshots sparingly... If you're only documenting dialogs,

a screenshot is redundant, but if your online help includes process

overviews, especially for new users, a screenshot can work wonders...

In some of these topics, I've included a screenshot in which the most

basic controls are alleviate dialog-box anxiety, and

show the user that only a few of the controls require their attention

for the particular process...I have waited for the program to mature

a good bit before adding those kinds of topics.
[U]se partial screenshots...when documenting the options in drop-down

lists, and when showing how changes to one control affect other

controls...[They] take up less space, on the screen and disk.


Debbie Pesach wrote:

1. [W]ork for accurate names for your interface elements and, as much

as possible, try to avoid inclusion of screen shots in the OLH. I

think that some usability studies have also shown that this can be

somewhat confusing and not very helpful to users. Just make sure that

you can roadmap as well as possible...screen shots can be very time


2. Avoiding humor, slang, & colloquialisms is almost always a good

idea. Try to avoid using words like THAT/THIS/THEY and instead

specify exactly what you are talking about... If your programmers use

text will have an easier time passing on text

messages/error message to the translator.

3. My approach to reviews is multi-level. I tend to print out content

at the topic level to have the appropriate SME (subject-matter

expert)check for technical accuracy and sign-off on the

addition to providing the SME with versions of the OLH as they are

compiled. The official link-checking is accomplished by myself (with

the help of ForeHelp's link checker) and by either QA...or one of the


4. ...keep a detailed record of what you do each day for this

project so that you can...get a sense of how long things took you and

where you got held up...


Previous by Author: Designing a new help system -- Oh boy! ...ugh
Next by Author: accents and umlauts
Previous by Thread: FrameMaker Resources [was 'RE: FrameMaker Oddity']
Next by Thread: Re: Agencies

What this post helpful? Share it with friends and colleagues:

Sponsored Ads