SUMMARY: Designing a new help system

["Rene Stephenson" <RStephenson -at- mwci -dot- mea -dot- com>]

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 

page...

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. ...as 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 

available...

-----

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 

ups. 

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

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

windows.

-----

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 numbered...to 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 

consuming...

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 bundles...you 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 topic...in 

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 

SME's...

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...

-----