Gathering Words
Writing is nothing more than gathering words. Some writers gather words from experience, some through observation, and others by research and interviews. Great writers assimilate information, gathering their words subconsciously, and jumble them on a page in a seemingly effortless exercise. Ignoring academic lists of acceptable modern greats, I'd point to John Irving as a prime example. The Hotel New Hampshire, Cider House Rules and The World According to Garp are effortless reads dripping with language.
I also like Irving because he thumbs his nose at critics. The best writers use their craft to (depending upon their mood) subdue, mock, ridicule, savage, or ruin a particular critic or all critics, class-action style. Milton did it. Heinlein did it. And Irving does it in A Widow for One Year. But this is an aside.
Publishing books about creative writing is a lucrative industry. Want to spend a few bucks in the hopes of picking up experience and skills? Buy a writing book. Cleanth Brooks wrote one. Rita Mae Brown has one. You could go cheap and read older classics on the subject: Francis Bacon, Sir Philip Sidney, and Henry James. Or choose one of the idiot, dummy, or moron guides. Choose your weapon, pick a few courses, drown yourself in Venti Lattes and late nights at the word processor, and have a go. Hundreds of eager professors await.
But what about technical writing? On a continuum anchored by creative writing on the one side and journalism on the other, technical writing lands somewhere near journalism.
<-- creative writing ----------------------------------tech writing----- jorunalism -->
No arguments, no emphasis on language (unless it is plain and direct), and little reliance on personal experience. At least when done well. Different skill set. And there are books to feed this fire as well. Mostly books with boring titles and written in the style of an Emily Post book on manners or an automotive wiring diagram. No syllogism here kids, move along. Just the facts. It is difficult to do well because the topic itself may be unappealing. Interjecting personal opinion or conjecture results in red marks and scowls from the editors. Nothing but the facts.
But what about writing about software development kits, application extensibility, and tools used by developers? Technical writing. No doubt. But there is room to cheat and move away from the journalism side of the continuum. Isn't there? Sure, rattling off lists of API's is about as creative as enumerating the parts in a sprocket assembly, but weaving the individual API's (facts) together? There is a spark in that. I can weave a dozen different method calls together in a dozen relevant ways depending upon the scenario I am trying to satisfy. I can link in related technology, different platforms, design patterns, languages, and design principles. The resulting sample or code snippet is still technical material and (hopefully) factual, but seems closer to creative writing.
Technical writing can become more creative as the technology and documentation evolves and matures. Once the API's and other facts have been captured, customers demand guidance. Supplying the hammer and technical manual isn't enough -- how do Steve, Norm and the Silva brothers use their hammers with seemingly perfect results whereas I always hit my thumb? Customers need troubleshooting (what to do when your thumb throws the "ThumbCrushedException" exception), best practices (how to hammer drywall without leaving dimples), limitations (hammer won't fix everything; check target for brittleness and overall suitability to being hammered before hammering) and samples (Building a Doghouse (Hammer SDK Sample) ).
I don't think we are at a point where documentation can be written in a more casual tone. While I might blog using an informal tone, it would be a stumbling block in the documentation. Sure, we all want to slip in a zinger every now and then (I still remember the Turbo C documentation entry for the sound() or tone() function that described the effects of playing a certain note at a certain frequency on chickens), but unless subtlety is used, there is a good chance the zinger will be flushed by editors or called out by annoyed customers. But I do think we should adopt a slightly less formal tone in documentation. I'm not sure how far we can go, but there is leeway.
Thoughts?