[Usability] Embedded help works better than standalone help

[Matthew Paul Thomas <mpt myrealbox com>]

On Mar 30, 2006, at 10:54 PM, Joachim Noreiko wrote:
> --- Reinout van Schouwen <reinouts gnome org> wrote:
> > Also, maybe a "lightbulb tip" could be shown that
> > users can drag pictures
> > to the icon field.
>
> It's best to avoid putting documentation in the
> interface. (There's a note in the HIG about this.)
> ...

Then the HIG is wrong. (Calum, to chapter 11 with a pair of scissors,  
please...) It is far, far better for brief explanations of how to use a  
window to go in the window itself, than in separate help where it is  
read much less often.
*   <http://winwriters.com/articles/checklist/>
*   <http://www.stc.org/ConfProceed/2003/PDFs/STC50-071.pdf>
*   <http://tc.eserver.org/10347.html> (first part available for free
    at <http://www.allbusiness.com/periodicals/article.asp?ID=686673>)
*   <http://keycontent.org/tiki-index.php?page=Embedding+UA>
*    
<http://klariti.com/technical-writing/Improve-Usability-Embedded- 
Help.shtml>

(I guess this reality is unfortunate from a documentation writer's  
point of view, because it means you need to spend more time crafting  
helpful sentences and posting them in Bugzilla, and less time crafting  
helpful paragraphs and checking them in directly.)

Help that appears in a separate help viewer should not explain  
individual windows, but should instead concentrate on solving the  
problems for which people typically go to the help system: (1)  
something's wrong and I want to fix it, and (2) I know this feature  
exists but I can't find it.
*   <http://blogs.msdn.com/jensenh/archive/2005/11/29/497861.aspx>
*   <http://g2meyer.com/usablehelp/lastreso.html>

Now that yelp has search, (2) can be catered for partly by including  
common misspellings and synonyms for each topic.

--
Matthew Paul Thomas
http://mpt.net.nz/