Documentation Driven Development!
So I was having lunch with our Programmer Writer, Tamra Myers the other day, and we got onto the conversation of documentation. I’m a huge Huge HUGE fan of documentation, in fact, when I coded in anger, I was known for my extensive, well written, downright Elizabethan doco.
I was then having lunch with Simon Guest on a different day and we got onto the topic of doco too, in fact, we were talking about some research he had done into how much of MSDN doco actually had code samples! You might start seeing a trend emerge… yes, I love to eat lunch with passionate doco people!
So what has this got to do with the price of Tzatziki in Redmond? Well, we all strive (in software engineering anyway) to build technology that people can use, or at least, work out how to use. If you build software, especially developer platform software, it’s not always easy to build highly intuitive APIs and components. So what’s left is the doco. The doco is the first port of call for the user of developer goo, in there, they can orientate themselves around the nuances and intricacies of a component and the bend it to their will. However, if you don’t provide doco, well then, you’re putting the developer user in a world of pain, and forcing them to make a choice. They can either try and hack away, using coincidental discovery to work out how your thing works, or try and find a blog post from someone who has. If they choose the former, they could waste a bunch of time and never hit paydirt, if the they choose the latter, there is always the chance that the code they are using is not optimal, or inline with the way the component/API was designed.
So why is there such poor doco? Well first of all, the engineering process if fundamentally broken. It starts with requirements, then specs, then code, then test, then release, then somewhere along the way, doco. Now, it’s like running a marathon, they always tell you to stretch and cool down afterwards, but for most of us, when you hit the finish line, you just want to pass out. Coding is the same, when you’ve squashed that last bug, and checked in your final build, the last thing you want to do is write your coding memoirs. However, herein lies the travesty! Because most of us don’t summon the last drops of energy to write good doco, all our hard work is wasted because know one knows where to find the secret red button that can transport us through space and time. Instead they are left to prod around the facade and try and find the switch.
How do you solve the problem? Start with doco first! Just like the industry realized that by putting testing after development, you’re putting the cart before the horse, putting doco before testing makes sure you stay true to what the customer is meant to have and what it’s meant to do. And more important, you can see how easy or usable your stuff is before you code it. I mean, how many of us have written a component, then given it to someone, had them ask us for a quick sample, then as you develop the sample you realize, “Damn, this is hard to use” or “I could have added a method that would have reduced this from 10 lines to 2 lines of code”? By starting with how should someone use the component, what it does, what are the inputs/outputs, exceptions, expected behavior, you have more than just the functional spec to work against. And, most importantly, when you’re ready to release, you have the best doco on earth, better than the code! To the customer anyway ;)
By the way, if you want to read more on this topic, check out the following paper:
Now go forth and doco!
Technorati Tags: Engineering