As developers we get often asked to write more, better and earlier documentation.
While it is very important and useful, to have the right documentation when needed and more often than not we are lacking important documentation, it is also important to avoid writing too much documentation.
This applies to all levels of documentation, including comments in the code (javadoc, scaladoc, rubydoc, perldoc,… as well as inline comments), design documentation, Wiki/Confluence, external documents.
Some projects measure the quantity of documentation, for example. Or the coverage of javadoc. And people start writing automatically generated or trivial comments on getters and setters. While there can be a comment documenting the attribute placed with the getter instead of the attribute itself, this is usually a bad idea, because it just clutters the code with no gain at all. Commenting should be limited to the non-obvious. And code should be written in such a way, that there is not more non-obvious than necessary. So code that is readable and understandable with few comments is actually a better goal.
For APIs we might want some more documentation. But we should keep it as close to the code as possible and use tools like swagger or scripts to create API-documentation from the code or code and documentation from the API-specification. This has a better chance of staying up to date, while hand maintained documentation always tends to get outdated over the time.
It is good to describe the overall working of the system. But details should be looked up in the code, where that is a viable option.
It is important to describe, how to get started. And even better, if getting started is easy because of automation, scripts or tools that do it in a few, relatively easy steps. This is a goal that everybody seems to have, but nobody seems to succeed with.
It is important to describe, how certain problems are solved in the team or have been solved, in terms of how it should be done to conform with other solutions or how it can successfully done. Guidelines are probably a good idea. Even better, if they can reference as much as possible well established guidelines published in the internet and just describe the exceptions or details about which the public guidelines do not make a decision, but that should be done coherently within the project.
And the business side of the software should of course be described also in documentation.
The agile manifesto recommends: „Working software over comprehensive documentation“.
But this should not stop us from writing documentation that really helps us.
Links
