I listened to a podcast a while back, can't quite remember which, where they were talking to a company that had started with internal blogging. The idea was that all staff got their own blog to write on and were encourage to do so whenever they had an idea or something else they felt could be interesting to share with others in the team, or across the teams. I didn't pay much attention to it at the time though, just though it a bit over the top to be honest. But today it kind of struck me that actually, it's a really good idea.
When everyone is busy with their tasks at hand ever so often someone gets an idea or finds something in their day to day work annoying but at the time there aren't really any forum to communicate this to fellow colleagues so it gets forgotten. Instead this can be captured in a blog post. This will allow for the idea or frustration to be available to others as well as the poster for later when it may come in handy. And as for frustrations in day to day tasks, if enough people find that they share the same frustration this is the point where it's time to do something about it.
So the long and short of it is that it's probably a really good idea to encourage an internal blogging culture in order to identify all the potentially lost opportunities for improvement that disappears in our day to day work.
I am currently working with an application I don't know very well, written for a domain I'm not overly familiar with. This is not an uncommon situation for developers but it can be eased considerably with good documentation. I find that especially well written Javadoc are invaluable since they will show up in the IDE where I need it the most.
So what are the key things to think about when trying to write good documentation that other developers will read? I think the following points are important to think about that will make the documentation valuable.
- Document what the class/method/field is/should do, not how it does it. The intent of a class/method/field is not always evident from its name but a line or two of Javadoc will make it so.
- Use a language that is understandable by the client as well as the developers. I tend to find documentation written in the language of the domain the application is solving, with specific words explained, easier to understand since it's easy to relate to the real world problem then. If the documentation is overly technical it's difficult to relate it back to the clients requirements and needs.
- Remember who you are writing for. Generally Javadoc are written for other developers. Developers tend to understand and know technology so there is no need to tell them how something was solved. That should be obvious from reading the code and any in line comments. What needs to be described is how the code solves the real world problem and what part of the domain it relates to.
- Javadocs are the contract. In my opinion Javadoc are used to detail what is the outcome of running a method or using a class/field. Like a contract. With some detail on how to use it if it's a public API method. It should not give me any detail on how it arrives to the result. This information is encapsulated in the code and the tests for the code.
If this documentation was readily available in the code base I am currently working my life would have been simpler. But then again perhaps it's a good thing that I start writing it since I now know what is missing. And perhaps the developer coming next will continue on this work since s/he will find other areas where documentation should have been added.