Archive for February 14th, 2007

A Culture of Documentation

I have been brewing this thought over the last week six months or so… what if we could build in developers a culture of documentation. The reason I have been having this thought is because it is the thing that developers hate to do and yet the thing that other developers most need.

I used to work in a great company (it was aquired by IBM) that employed a really good technical writer to do all the help for the users, the training material and other outputs that the company needed.

That is all well and good but developers should take responsibility of their own documentation. I am not suggesting that they should have the scope of documentation that this technical writer did but there is room for improvement in most cases.

This starts with self-documenting code. Use of standard and consistant naming conventions across the codebase will mean that developers will be able to recognise what is going on more easily, especially if the variables are named with meaningful variable names.

Secondly, the code should be well commented. This should include a flower-box or equivalent for your language at the top of the file to describe the purpose of the file. Hopefully this will be able to be parsed by some automatic documenting tool like javaDoc or PhpDoc to generate documentation for the project.

Thirdly there should must be some source control. If you are in a development team of greater that zero then you must use source control. I have been using subversion for projects I have been working on for over a year now and there is no way that I would go back. Even if the project I was working on was a personal project. If you don’t want to go to the bother of setting up a subversion server of your own then use google’s new code service.

Fourthly, use a wiki. Wiki’s are a great way to easily capture documentation that can be shared with your developement team. It’s easy to create a heirarchy of pages that can be navigated or bookmarked for future reference. I find this particularly useful for tasks that I do regularly but not often enough to remember how they work. I can quickly check customised version of command that I need to issue or screenshots to check that I am on the right track.

Lastly, and I am thinking of SAP here, if there is scope in your development platform for capturing documentation, then capure it. There are lots of places for capturing documentation in an SAP project. All custom dictionary objects can be documented, all reports can be documented, all classes can be documented… need I go on? What can be a tad annoying with SAP is finding that there is no documentation in these standard places for SAP delivered objects.

No documentation available

Lets reverse this trend and employ a culture of documentation. What are your thoughts? How can we get developers to realise the importance of documentation? and then actually DO it?

Technorati Tags: , , , , , , , ,