How to Draw an Owl

On Documentation

One recent afternoon I found myself in deep conversation with potential consulting partners, holding out for a difficult requirement: “Excellent Documentation”. That’s a tough one to quantify, let alone describe; why hold out for something at once critical and ineffable? Doesn’t every project talk about the importance of providing documentation, yet rarely deliver it? Don’t most people flip past the pages of detailed work process, going right to the keyboard to bang away, expecting tool tips and intuitive UI to guide them through? Aren’t most technical teams passive-aggressive on documentation, procrastinating until the final week, throwing something together that the project manager probably doesn’t have time to read and review?

Still, I will press on candidate firms that want to code/configure for me, to put their manual where there mouth is, and show samples of the documentation that truly allows me to become self-sufficient. Many will piously claim an ultimate goal; to walk away from the project and customer [me], leaving me fully trained and self-supporting – even though [he cynically observes] they are incented to maximize billable hours. (Yes, I know the real truth; consultants enjoy the “fun stuff” – coding from scratch / developing new. Maintenance, extensions, and bug fixing gets boring.)

Of course, the more thoughtful Business Development folks, having been through similar conceptual wringers, will point out the difficulty of quantifying “acceptable”. But it’s not difficult to visualize; like certain non-fiction books, the really well-written ones where structure and prose come together in a perfectly natural way. “It’s like God wrote that”, I like to say, “it couldn’t have been written any other way.” Sort of like the Potter Stewart Pornography Test – “you know it when you see it”.

On Books

This turned the conversation towards books in general – fiction or non-fiction, read for enjoyment only, without regard to platform (paper or plastic). In fact, this is a terrific interview question I like to spring on folks – What as the last good book you read? It’s interesting how often the technical folks respond with Kernighan and Ritchie or the Gang of Four (no no yes), but I really like to talk to folks who want to review the latest pulpy summer fiction, interesting history, or a real brain bender like Hofstadter or Kurzweil. This is a great way to get into how people really think – listen to someone get animated about arcane topics like how to measure things – really big things, conceptually impossible things. You can hear it in their voice, see it in their body language – and it’s this honesty and energy that you want working for you, on the project or the contract …

Back to the Documentation

… and that’s probably the best way to identify an excellent documentation writer – do they get excited and animated about the craft of good writing. Do they know it when they see it – and can they identify why it works for them?

In the end, I agree that this is my white whale, a recurring windmill against which I tilt. Why do people overcomplicate the pictures and the prose, and create confusion out of something straightforward? Is it lack of complete knowledge about the subject matter – or lack of ability to communicate complexity with simplicity?

No easy answers here, and we’re running out of our scheduled time. To help make my decision, I’ll ask for samples; I find the best way to request representative work is to ask for something that the candidate is “proud of”.

Epilogue

An excellent quote near the end of this conversation; “I don’t read manuals … I clunk, I’m a clunker … I Apple” [emphasis mine]. Fascinating how intuitive usability has made a verb out of a brand name and a design philosophy.

Originally published on cazh1.com