Re: On-screen hints

[Janet Swisher <jmswisher -at- gmail -dot- com>]

I concur with Richard's assessment. Having useful embedded user
assistance could be a huge win for users, but may not be supported by
your standard help-authoring tools. Seek alliances which those in the
"pro-hint" faction of the political battle, if you can.

I worked on a system where we had embedded help similar to your first
case ("You appear to have a broken link"). In that system, the hints
offered strategies rather than procedures (e.g., "Change either height
or width so that height is less than width"). In cases where there was
more detail than would fit in the help pane, we provided links into a
library of best-practices documents. You could do the same with links
into traditional online help.

--Janet

On Fri, Jan 15, 2010 at 10:53 AM, Combs, Richard
<richard -dot- combs -at- polycom -dot- com> wrote:
> 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.
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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