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/ _______________________________________________ desktop-devel-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
