Re: quo vadis, docs

[Matthew Paul Thomas <mpt myrealbox com>]

On Feb 9, 2009, at 5:43 PM, Tristan Van Berkom wrote:
> On Mon, Feb 9, 2009 at 11:52 AM, Luis Villa <luis tieguy org> wrote:
> [...]
> > Amen. I've often felt developers should be required to document their
> > own UI changes :) Heck, simply asking 'what does this dialog mean'
> > would be useful a lot of the time...[1]
>
> Luis do you write software ?
>
> Not that its important that you do, but just to clarify the issue;
> "simply asking what does this dialog mean" in the long run usually 
> means:
>    - Take a screen shot of the dialog

I have good news: Usually taking a screenshot of a dialog for the help 
is a really bad idea, so you don't need to do it. ;-) Often it doesn't 
add any insight to the text, sometimes it gets mistaken for the actual 
interface (as both Novell[1] and Apple[2] have seen), if it's big it 
won't fit inside a usefully small help window, and it makes the help 
much harder to localize.

[1] <http://tinyurl.com/brtw4d> (6 minutes video, 48 MB)
[2] <http://tinyurl.com/d65n9s>

>    - Open the html or whatever the docs are written in
>    - take time to format the docs/text/images in a readable way

Yes, that's the hard part.

>    - take time to properly describe your feature or functionality

More good news: That's also often unnecessary. A description of a 
feature in checkbox-by-checkbox detail is just as boring to read as it 
is to write. Instead, think: What are the most likely reasons someone 
will have trouble here? And what things are people most likely to be 
looking for under a different name? Answer those questions (without 
phrasing them as questions) in two or three paragraphs each.
<http://tinyurl.com/clrt3o> Do that, and you'll have something more 
readable and more useful than ye olde Gnome Application Manuelle V2.7.

> ...
> I am going to generalize here and guess that if you are not GTK+,
> and you are not epiphany or gimp - then its pretty much safe to
> say you are a one man team plus the occasional extra guy, or
> a few randomly submitted patches (which often generate more work
> for the maintainer than bugs fixed or features implemented) - you can 
> hardly find time to update the website when you make a release, much 
> less spend time writing user docs.
> ...

Maybe so, but that doesn't make a completely out-of-date set of help 
pages any less embarrassing than a completely out-of-date dialog or 
menu or splash screen. You could be relying on the assumption that 
no-one reads the help, so hey, doesn't matter if it's completely wrong 
-- but why take the risk?

Instead, I suggest *not having help* unless you have someone on your 
project team willing and able to keep it up to date. Having the help 
author actively involved in your project makes it more likely that 
they'll ask you (or know the answer to) the questions that make the 
help insightful <http://tinyurl.com/bov9oh>. It also makes it more 
likely that they'll suggest you improve the interface instead, or at 
least embed the help into the application itself where it's much more 
likely to be read 
<http://keycontent.org/tiki-index.php?page=Embedding+UA>. And not 
having help until then protects users from the breach of trust that 
would keep them away from the help even after it became accurate
<http://www.uie.com/articles/documentation/>: "Once they’re burned by 
the docs, users typically won’t look there again. Unfortunately, this 
behavior can persist even after developers fix a problem."

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