Loud Thinking: Challenging life, software, and media
Sunday, December 2, 2001 @ 00:45 | Challenge?

Operation Cheerful: Clarity expendable

As I'm reading Philip Grenspun's why most computer books suck, I can't help but draw a big smile. This is exactly how we had to write documentation and tutorials at my old job. Keep the cheerful spirit up at all costs. Clarity expendable.

Saving developers hours of frustration was not an option, if it detailed admitting the product was flawed in any way. The poor programmer using our software (a collection of community tools) had to learn all it's quirks, of which there were many, the hard. We knew perfectly well where the software sucked, but couldn't tell.

This prioritation was enforced by documentation reviews where presetation was king, technical details the starved peasant. Reviews were conducted not by the developer's peers, who would actually be able to provide meningful feedback, but by a manager far removed from the code. The result? Documentation that obeyed the rules of grammar, but failed to do customers much good.

That developers reading the documentation wouldn't have any thing to do with the purchase decision, the only justification I can think of, however falliable, seemed lost on the management.

Good documenters works by teaching programmers how to make the most of the software in the least amount of time. Everything else is a distant second.

Challenge the Loud Thinking

Got love or hate to share? Write me!

- Danish Design of '79
- Biz/CS student
- Web developer

- Dave Winer
- John Robb
- Michael Barrish
- Mark Pilgrim
- Evan Williams
- Joel Spolsky
- Glenn Fleishman
- Cameron Barrett
- Zimran Ahmed
- Phill Wolff
- Robert Scoble
- JD Lasica
- Gail Armstrong
- Malthe Sigurdsson
- Jeppe Kruse
- Jakob Skjerning
- Tinka
- Yami
- Thomas Madsen-Mygdal

- Becky (Emailer)
- The Brain (?)
- NoteMap (Outliner)
- UltraEdit (Editor)
- NetCaptor (Browser)
- WebDrive (FTP)
- Gamespy 3D (Gaming)

Utada Hikaru / Red Hot Ch P / Beth Orton / Sade / Jewel / Randi Laubek