Ionrock Dot Org

The last few few weeks Uche and I have been working on a project. It has been a great experience in that I have learned a ton. It has also been extremely frustrating because it has made clear my skills documenting are terrible. The biggest issue is that I simply don't enjoy writing documentation. There are a very select few who really enjoy documenting the mundane and technical, many of whom I've had the privilege of helping. It is too bad that I didn't manage to pick up a desire to be a better documentarian.

The biggest issue I have is adding enough detail. I might outline the basics, but you always have to consider when something goes wrong. This doesn't mean that every possibility needs to be documented, but having a few obvious routes for debugging can be a real help. Again, what denotes a piece of information is always going to be subjective, but one man's trash is another man's treasure, so you never know when the small reference to a specific class that handles a critical piece can help someone save an hour.

I doubt I will ever be a pro when it comes to documenting. I would rather write code for the time being. It is clear though, that as my code becomes used by more people, it will need better documentation. While now is not the best time, hopefully I'll catch the documentation bug and get my head out Python/Ruby mode for a little more reStructuredText/Wiki Text.