Documentation Is King

I recently stumbled on a Java/.Net open source project called BouncyCastle when I was running into issues using Microsoft’s implementations of RSA in the .Net Framework. I thought to myself, “Open source to the rescue again!”, Boy was I wrong. Let me go on records as saying it’s a good project and has a ton of useful API’s in it, the problem there is no documentation or examples.

There are a lot of open source frameworks out there. But there are very little that are truly great. I believe this is because people are so into the code and the architecture that they forget that there may be other people using the framework. This is why, documentation is king of your project!

If you are publishing a framework for other people to use without any kind of documentation you really have failed. Even the smallest of frameworks should have a little bit of documentation. Frameworks especially should have well documented samples. If your potential user is browsing your unit tests trying to figure out how things works, there is a problem.

Here is a checklist that I think is a must have for any framework:

1. Easily to navigate website (i.e. CommunityServer/Wiki)
2. HTML documentation on the site
3. CHM or VSDoc with the download package
4. Samples of the 80% (common) scenarios with the download package
5. Forums or other web community system (not a mailing list!)

There is an old adage when it comes to documentation and is goes something like this; “Outdated documentation is worse then no documentation”. That is a bald face lie put out by people who would prefer to never write documentation. Old documentation can be really confusing and frustration but what it does provide is a sign that could point someone in the general direction.

At the time of this writing I’m trying to figure out why BouncyCastle’s RSA implementation just spit out garbage to me. Was it padding? Did my encoding not work right? Was I calling the correct thing? I don’t know and because there are no samples or any documentation to speak of trying to orient myself in the right direction is a difficult task. Frameworks are supposed to make developers lives easer by making complex tasks simple, but without a solid foundation of documentation, samples and community it only adds more work.