RE: On-screen hints

["Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>]

Viv Crawford wrote:
 
> The software has been designed to have hints on screen in a movable,
> dockable panel, that the user can choose to switch off.
<snip> 

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

You need to talk to and work with the responsible engineer(s). Someone
controls when the hints change and where the hint text is stored -- if
the engineers follow good programming practices, that's in a resource
(text) file, and not embedded in the source code. Assuming that's the
case, there's probably an ID or key associated with each screen, and
it's mapped to some text somewhere. There's no reason two consecutive
screens can't be mapped to the same hint text (it may require duplicate
entries of that text, an easy copy/paste operation). 

Embedded user assistance is a great idea, don't discard it due to a
failure to communicate. 
 
> The various problems I see with this approach are:
> *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.

The details depend on the development environment, but this is most
likely a plain text file that maps IDs or keywords to the text strings
to be displayed. Entries might look like this: 

securityconfig.securemode.description=High security mode disables
unencrypted protocols and non-essential access methods.

The granularity and flexibility is likely to be whatever the engineer
who wrote that code decided, and ought to be changeable and negotiable
(within reason and subject to time/resource constraints). For instance,
there may be one hint text object for each screen displayed, but you
ought to be able to say, "For screen 6, I want to display these 4 text
strings in the hint panel and highlight the second. For screen 7, I want
to display the same 4 and highlight the third. ... How can we do that?" 

I'd make creating these hints the first priority. If you do a good job
with them, users will turn to the online help and print manual far less
often. No, you probably can't single-source (barring a fancy DB-driven
content management system), but you can "borrow" text snippets from the
help/manual source files when appropriate, or more likely (if you
address the hints first) "borrow" hint text to reuse in the help/manual.


HTH!

Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-777-0436
------






^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
http://www.doctohelp.com/ 

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:
http://www.ModernAnalyst.com

---
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:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat