“We must write more documentation”. Have you heard that? I have, many times in many companies. Most people feel guilty for not writing documentation and agree. I don’t.
There are two types of documentation – in-code and external. In-code documentation consists of javadoc (or whatever language/tool you are using to describe what classes and their methods do) and comments. External documentation consists of documents or intranet articles describing what the product does.
Rule number one of external documentation: it goes out of date. And keeping it in sync is a tedious and time-consuming task.
Rule number two of external documentation: nobody actually uses it.
Programmers work with code. They are good at reading code. And code makes perfect sense to them. Documenting the core classes and any non-trivial use-case within a method is part of coding best practices, and good programmers do that. It makes understanding the code much easier for other people, and together with writing self-documenting code, it is an entirely sufficient documentation. And it doesn’t need keeping in sync (well, apart from changing a comment above a snippet).
So do you need external documentation? Well, yes, some of it. It is important to make a very succinct description of the overall architecture, so that the pieces of code make sense in a broader context. What are the modules and how they interact – that’s enough, one page. It will also go out of sync, but at least it’s easy to support and it might be the duty of the team lead / architect to verify its validity every now and then.
And now, if you are a QA or a manager, you’d say that you don’t understand the code and you need the documentation in order to do you work. I might sound a bit rude here, but if you need something, do it yourself. Developers are not technical writers and keeping external documentation is not something they enjoy or need. And if you don’t want to do the documentation, but you still insist you need to know what’s happening, then just ask the developers. They’ll be happy to read the code and explain the behaviour. And what if there’s a mismatch between the behaviour of the code and the expected behaviour? Then check the issue tracking system and see what has been requested. You don’t need external documents describing what the code does.
Of course, software that is to be used by end users would need some sort of user manual in addition to the in-code documentation, but that can be kept to a minimum as well and should be written by other people, if possible.
So, next time someone insists on programmers writing documents describing what the code is doing, do not agree with them. Insists that it’s a waste of effort and that code and comments are sufficient. If they aren’t, then you need better programming standards and habits, not documentation.
I agree with most of the article’s points. However some times documentation is really useful and it can’t be painless. I invite you to read the following article which discuss exactly this topic : http://www.java-tv.com/2012/07/09/simplify-your-java-documentation-strategy/
Very good article. I’m preparing one about the same theme, but in spanish. I’s been a good reading as an apport for mine. Keep on doing so good job.
agree but programmers develop code based on the functional requirements. The functional requirements have to be documented and signed off by the sponsor. The documentation is a pain but essential for the successful development and maintenance of the application. So I don’t agree with the article.