HTMList.com

Coders like to code; coders don’t like to write. It’s no secret that thorough and approachable documentation is a rarity in the coding world. Despite its necessity for the adoptability of a given software package, finding good documentation is notoriously difficult. I’ve seen “documentation” consist of a simple phpDocumentor run. To the folks at Magento: this is NOT DOCUMENTATION!!! It’s merely is an incomplete reference guide!

Maybe it’s because I’m not the greatest coder this side of the Mississippi, or perhaps because I actually have an interest in writing English, but I, for one, like to write documentation. In past projects, I have begged bosses and project managers to allocate time for me to document the code that I have written (every time I was denied…by the way). [Not the case here, for the record. We love documentation and Brandon's new. He'll come to see that. :-) —Ed] Good documentation, whether for internal applications or publicly available code bases is nearly as important as the code itself. Here’s why, after the jump.

Why develop good internal documentation?

• Sorry to say this folks, but employees leave. They get better jobs, or get fired, or for some reason or another leave your organization. By having your coders maintain well written documentation you give yourself two advantages:

1. You protect yourself against workers leaving with legacy application knowledge, and
2. You shorten the ramp-up time of the new employees that take over the application.

• You automatically create a lasting knowledge base for any problems that might arise in the future. A documentation system, if properly designed and maintained, can make finding obscure answers to even more obscure problems take much less time.

And what about good external documentation?

• PEOPLE MIGHT ACTUALLY USE IT!! Yes, this is an obvious one but think about it: there are only a few truly elite coders for whatever system you may developing. They are the people who will be able to (and more importantly, have the time to) manually go through your API and automagically know how to develop within it. Now, the other 90% of programmers that will be using your product (who may be very good programmers but left the Matrix years ago) could perhaps use a natural language interpretation of what you’ve developed. This obviously expands the reach of your product (and hence the adoption rate) while exemplifying the nuances of your coding genius.
• It also shows your dedication and attitude on software development. For instance, what would you say if you bought a new car and it didn’t come with a manual? Sure, you probably already know how to drive it, but what about the viscosity of the oil it uses? Or maybe the recommended service intervals? Without the manual, it would appear that the car manufacturer didn’t really care much about your experience with their product.

So we know that documentation is a good thing, but the problem really seems to be, “what makes good documentation?”

Put simply, good documentation should:

• Be able to take an individual with average programming ability and allow them to understand AND implement about 90% of your product. The more features you document properly, the more useful people will find your product.
• Take a building block approach to developing. Start out with the basics but then progress, using your previous topics, into more robust and complex designs and implementations.
• Provide valid and WORKING code samples in each documentation topic that allow the user to follow along and progress with the documentation. People love to develop into examples. If you provide them with great starting points for features and comprehensive examples that demonstrate the potential of your more impressive features, developers will run with it and make their own magic.
• Provide a reference of all classes, methods and variables (inherited, etc), along with sample usage of each. I suppose a phpDocumentor-like output would work here but I strongly feel that code samples which detail abbreviated usages is very important.
• Be written as if you were writing to a teenage programmer (or intern). I’m sure I will get a lot of negative feedback on this one but there’s a reason USA Today is in such wide circulation…not because they provide great news stories with college-level English (which they don’t), but rather because they assume little and walk their readers through the details of the story. This is the type of approach good documentation should have. It must be accessible by the majority.

Now this is not to say that documentation needs to be completely dumbed down. By its very nature it can’t be. What we are dealing with here are quite often the highly complex interactions of code and design. But what we as coders and developers can do is provide a solid foundation for others, to help them get a handle on our creations as best they can. This is a best practice for not only the success of our code but for the success of other coders as well.

A relatively decent exmaple of this documentation philosophy is the Google Maps API documentation. It includes nice code samples and progression. If you have any other exmaples of good code documentation, please post and let us know! [And please share any other guidelines by which you try to document your code and your projects. Or any rants about projects you've seen ruined by poor documentation.—Ed]

Tagged with: adoption, best practices, code, comments, documentation, knowledge, legacy, phpdocumentor, projects

Posted in: Development, How To, Rants