Documentation is a fancy word for a simple concept. Documentation is nothing more than recording how something works so that someone else can figure it out. Despite it being a simple concept it is really hard to do right. Things change constantly and documentation needs to be flexible and dynamic so it can change accordingly. Much of the time this change doesn’t happen or only happens haphazardly and when you want to learn about how something works you have to stumble through the documentation and figure out any gaps yourself or with a Google result from Stack Overflow.
I read a comment today where someone said that to them the best documentation is a sample program that implements the code you want to teach. That comment made me realize that I’d been assuming that everyone has the same opinion about what good documentation is but obviously that isn’t true. Personally I hate seeing a sample program because the details I want to learn get lost in the noise of the rest of the project. Having a sample program isn’t bad but it certainly isn’t enough – I want the documentation to walk me through common use cases.
I’ve been thinking about this topic this week because Stack Overflow came out with a new documentation product. They want to do the same thing for documentation that they did for technical questions and provide the place on the internet that people can find the documentation they need. I’ve been an early beta tester of it for a few months but I never had a chance to dig in and check it out. I took some time a few days ago and so far I’m not impressed by what I see but I’m no expert at the right way to build such a thing. Despite that, my complaint is the from what I looked at the documentation was very topic driven – information about a control that can be used in iOS – rather than what I see as more concept driven like how to get started building an app.
Despite my poor first impression I’m excited about what this new documentation product will be in the future. I’m confident the Stack Overflow team will refine the idea until it is an excellent solution.