Home » Software Development » We Don’t Need That Documentation

About Bozhidar Bozhanov

Bozhidar Bozhanov
Senior Java developer, one of the top stackoverflow users, fluent with Java and Java technology stacks - Spring, JPA, JavaEE, as well as Android, Scala and any framework you throw at him. creator of Computoser - an algorithmic music composer. Worked on telecom projects, e-government and large-scale online recruitment and navigation platforms.

We Don’t Need That Documentation

“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.
 

Reference: We Don’t Need That Documentation from our JCG partner Bozhidar Bozhanov at the Bozho’s tech blog blog.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

 

3 comments

  1. 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/

  2. 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.

  3. sunitha raghurajan

    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.

Leave a Reply

Your email address will not be published. Required fields are marked *

*


Want to take your Java Skills to the next level?
Grab our programming books for FREE!
  • Save time by leveraging our field-tested solutions to common problems.
  • The books cover a wide range of topics, from JPA and JUnit, to JMeter and Android.
  • Each book comes as a standalone guide (with source code provided), so that you use it as reference.
Last Step ...

Where should we send the free eBooks?

Good Work!
To download the books, please verify your email address by following the instructions found on the email we just sent you.