Documentation – do I have to write it?
I heard some time ago someone saying half seriously: “It was hard to write, why it should be easy to understand?”
Leaving joke aside, is documentation necessary? I would definitely say YES. And there is no solid reason against it. Let’s discuss the possible concerns that you may have against.
Power position. If you are the only one that knows the inner workings of the code, you are tempted to say that you are on the safe side. True, but maybe if you are the only one working on that project, which I would say that anyway puts you in a power position. But as nowadays everything happens in a team, sooner or later someone would like/have to understand and use your code. And then the so called job security may resume to your value and the value of your code. Which you will further see it is heavily influenced by the documentation. And anyway, personally, I like to be measured by both the value that I brought and the one that I can still bring in the future.
Lost time. This is the most common argument when it comes to documentation. You will hear the developer saying “I barely have the time writing the code, I don’t have time to also document it.” In a marathon it is said that if you don’t know how to dose your effort, whatever time you will make in the beginning by running much faster than usual, you will lose twice in the end. In software development, I would say that it is even worst. If you don’t document, that ratio can be even 1:10. But why?
To better understand let’s see the pro reason – why to document your code?
Better understanding. When you document your code, you explain it in a more formal way. It’s like you will teach a class of students about your application inner workings. If the application architecture and coding are not clear, it will be harder to explain. This way architectural or coding issues will surface right from the beginning. That is if you document right from the beginning :).
Shorter learning curve. New members in the team or in the project will be able to easily understand and catch up. And most importantly they will be able to do this on their own without wasting other people’s time on explanations. And if the development team is split between multiple projects, you’ll be able to share resources much easier.
Easier maintenance. The nice part is that the documentation could even help yourself. If you don’t touch an application for at least six months, you will thank yourself if you documented it.
Sooner or later writing documentation will pay off. To make it sooner, in the end, I would like to share with you a few guidelines about writing documentation.
- Be clear and concise. Write only as much as it is necessary to understand the system. Write documentation like you will explain it to the others, not to yourself.
- Don’t make assumptions. Don’t think that some parts are already known unless you explained them before. Suppose that the reader doesn’t know anything else, except what’s in the documentation.
- Write only if it’s adding value. JavaDoc comments like
The XClass class.or
Sets the name(for setName method) does not say anything that you didn’t know already. In my view if the name is self-explanatory, the documentation is not necessary. But instead just describe the specifics.
- Use references where appropriate. Reuse documentation the same way you reuse code and don’t describe the same thing twice. It was already documented even on an external resource, reference that one instead of explaining the entire thing. At most you can include a short summary. If you’re using the Spring Controller in your web application, does not make any sense to explain the entire Spring MVC.
- Use easy-to-use tools. Write documentation using tools that are easy to use and to which your team members are acquainted and confortable with. Make documenting really easy. To get developers write documentation you already have to fight with a somewhat negative mindset, don’t make your life harder and fight against the tools too.
- Use collaborative tools. Do not write documentation in Word documents, PowerPoint presentations or similar and do not send any documents by email. Use a central place for your documentation and use references in your communications. This will help you consolidate your effort and change the mindset. Shortly you will see that everyone will refer to that central documentation point instead of just asking different people.
- Leverage templates. If you already made a habit of writing documentation some patterns and templates will emerge. Use them – reuse is always good.
Most of the unsuccessful open source projects are in this position because of lack of documentation. Many commercial projects are over time and over budget because of the same reason. Don’t say it’s not worth, unless you REALLY tried.