Brent Simmons writes “... it’s good for engineers and architects to write docs because it makes the software better.”
No. NO. NO!
Engineers, architects, writers, and others should collaborate on documentation. The collaboration should be based upon engineers and architects serving as subject matter experts for the writer. But mostly, each should be doing what she does best. Engineers should engineer, architects should architect, writers should write. You get the picture. Remember Mr. Natural’s maxim: “use the right tool for the job.” That’s what makes software better.
I’ve spent the last six months trying to learn and understand UserLand Frontier. It’s been both rewarding and frustrating. Rewarding because it’s the only reasonably priced, reasonably robust, content management system that doesn’t suck. Frustrating because the documentation is written by the people who wrote the software.
It’s not that the procedures are confusing or misleading or even badly written. It’s that there’s a lot more to quality technical writing than “push this to make that happen.”
The above referenced procedure deals with getting Frontier’s search engine to work. The “Make a macro legal” bit brought me to my knees. First it’s talking about a version of Frontier that’s a generation behind where I was at the time. Who knows if it’s still applicable. Nowhere does it explain what a macro is or why it’s required for the search engine or why some are allowed or what legaltags are or why those that are not allowed are neutered (yikes). And so on. It’s written by a programmer for a programmer in a style that is comfortable for programmers but makes the rest of us nervous.
Real people can’t parse a sentence like, “If you call it with the name of a script you want to allow in templates, stories and discussion group messages, it will automatically program the legalMacros table to allow it.” Even if we all agree on what the definition of “it” is.
Documentation for a product designed to be used by non-engineers desperately needs a user’s perspective. Engineer’s can’t do it (at least not for their own projects). They know too much.
0 responses. Comments closed for this article.