On-screen hints

Subject: On-screen hints
From: Viv Crawford <viv_crawford -at- hotmail -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 13 Jan 2010 16:29:16 +0000

I have an interesting problem here that I would love to hear your thoughts on.

We are releasing a brand new software product. The software itself is near completion, the doc isn't started (and I'm new in post).

The software has been designed to have hints on screen in a movable, dockable panel, that the user can choose to switch off.

The hints are of two types. The first detects any problems you may be having in the main workspace and tells you how to fix it. (For example, 'You appear to have a broken link. To fix the broken link, do XYZ'. ) The second is a type of context sensitive help.

You are working with colours.
If you want to create a new colour;
1) Click XYZ.
2) Pick a colour from the colour palette.
3) Click save.

However, the hints change whenever the screen does. So when a user performs step one, they lose the hint containing step 2 onwards. The previous tech author attempted to get round this by writing the steps this way:

You are working with colours. If you want to create a new colour;
* Click XYZ and follow the instructions in the next hints panel.

The 'next' hints panel then says:

You are working with colours. If you want to create a new colour;
* Pick a colour from the colour palette and follow the instructions in the next hints panel.

The various problems I see with this approach are:
* The complexity of writing the hints as has been done presently means they are likely to be less than comprehensive. This may lead to the user switching them off prematurely and/or not seeking additional help elsewhere.
*I can't see how I can create these hints at the same time as producing regular online help and print manuals. Normally, I would single-source (in Flare), but I'm not sure this would be achievable.

I've now been asked whether we should remove these hints completely or to justify the extra time/effort/cost/delay to software. Obviously, it would make my life a whole heap easier to not have them, but I'm *extremely* reluctant to give up the opportunity to have user assistance on-screen at the point of need. It's also become something of a political hot potato.

So my questions are: Have any of you any experience of doing something similar? Is there a workflow that could keep this relatively straightforward? Is having on-screen user assistance worth the extra effort?

Any and all thoughts appreciated.
Thank you!
Viv (Long-time lurker…)

We want to hear all your funny, exciting and crazy Hotmail stories. Tell us now

Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at:

Explore CAREER options and paths related to Technical Writing,
learn to create SOFTWARE REQUIREMENTS documents, and
get tips on FUNCTIONAL SPECIFICATION best practices. Free at:

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:


Previous by Author: Double-edged sword (was Re: Mixing metaphors?)
Next by Author: Hyperlinks in PDF -- should they be visible or not?
Previous by Thread: Re: Integrating movies into documentation (Erika Yanovich)
Next by Thread: RE: On-screen hints

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

Sponsored Ads