Re: Nine Months in Six Months

[Matthew Paul Thomas <mpt myrealbox com>]

On Sep 10, 2006, at 8:31 AM, Nickolay V. Shmyrev wrote:
> ...
> [Shaun McCance wrote:]
> > But now you want all these programmers to assemble their 
> > documentation piecemeal as they add features?
> >
> > Even if they all had perfect English (which they don't), and even if 
> > they were all really good at explaining things (which they aren't), 
> > this would still produce bad documentation.  Why?  Because it would 
> > only ever produce "What's this?" documents, and never "How do I?" 
> > documents.
> >
> > I find myself shooting down this idea every single release cycle.
> ...

I humbly suggest that as long as you keep shooting it down, you will 
keep having the problem of not enough time to write "documentation".

Calling it "documentation" almost enforces the problem, suggesting that 
you're documenting something that has already been written. But just as 
with the interaction design, and just as with the test suite, you'll 
often get better results if the help for a feature is written before 
the code. The goal of all these disciplines is to maximize the 
proportion of people who use the software successfully, and it makes 
little sense to treat any of them as completely separate from the 
others.

I haven't seen anyone claim that programmers are usually good at 
writing help; it would be surprising if they were. But whenever they're 
not, they should team up with someone who is. Just as they should team 
up with someone good at interaction design, and someone good at 
thinking up test cases. For each module in Gnome (as I said on 
gnome-doc-list last month), you should be able to ask, "who is the 
maintainer, who is the interaction designer, who is the QA engineer, 
and who is the help author", and get three or four distinct answers.

> ...
> Agree, it's really a problem, but look at usability guys, they all just
> do a review, interface is created by developers. Developers are
> certainly not professional UI designers but HIG shows them the correct
> direction. It's much easier to review something and correct mistakes
> then to write it from scratch.
> ...

That is very far from the truth. It is much, much easier to correct 
usability mistakes before the code has been written than after.
<http://urlx.org/upassoc.org/1f8d2>

As for the HIGs, they mostly specify style for low-level things like 
appropriate window types, controls, spacing, and wording. Not having to 
constantly debate those things can save people a lot of time. But they 
are only a small part of design; they don't address fundamental design 
problems. (The most common such problem: "This shouldn't be a separate 
program, it should be a menu item in program X".) No book of guidelines 
can turn a musician into a composer, a surgeon into a medical 
researcher, or a programmer into an interaction designer.

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