Take the 2-minute tour ×

How much technical (for future developers) documentation is enough? Is there a ratio between hours coding and hours documenting that's appropriate?

Papadimoulis argues that you should

produce the least amount of documentation needed to facilitate the most understanding,

Is that a good guideline, or are there specific things I should be creating?

share|improve this question
End user / UI or technical / source code documentation ? –  user2567 Oct 6 '10 at 13:02
For source code advice, see our site's first question: programmers.stackexchange.com/questions/1/… –  Tom Wijsman Oct 6 '10 at 17:21
add comment

8 Answers

up vote 16 down vote accepted

How about some hallway usability testing? Show the code and documentation to a developer unfamiliar with the project. When you can do that without an overwhelming urge to explain something while watching them review the code, you have enough.

share|improve this answer
+1 I do like that idea too. Develop your software so it's so intuitive that documentation is not necessary. –  user2567 Oct 6 '10 at 15:26
add comment

La perfection est atteinte non pas quand il n’y a plus rien à ajouter, mais quand il n’y a plus rien à retirer.
Antoine de Saint-Exupéry

(in English: Perfection is not reached when there is nothing more to be added, but when there is nothing more to be removed).
share|improve this answer
So a project where all the documentation has been removed, is perfect? –  user1249 May 28 '12 at 14:07
@ThorbjørnRavnAndersen - No, perfection is achieved when removing any more content would undermine the worth of the documentation as a whole. –  cjmUK May 28 '12 at 14:14
@cjmUK and how does that interpretation answer the question asked? –  user1249 May 28 '12 at 15:12
@ThorbjørnRavnAndersen. It doesn't; it was a comment in response to your comment- which, for the record, I suspect was a misinterpretation of Benoit's answer. Only Benoit can answer for sure. However, my answer is listed elsewhere... –  cjmUK May 28 '12 at 15:35
Wrong. It means more is not necessarily better. Brevity is to be valued, but clearly not if making something simpler means missing out on useful information. But equally, writing volumes and volumes of documentation might make it harder for another developer to access to the most useful information. When writing documentation, you don't simply need to think about what is still missing, but also what you have that you don't really need. –  cjmUK May 28 '12 at 16:37
show 3 more comments

I've been thinking about this topic for a while.

My conclusion is - it's not a matter of quantity, but of quality and context.

For example, a proper project structure beats comments explaining where the files are located (implementation vs. intension)

Similarily, classification to clarify context beats naming (Id on a Patient -> Patient.Id).

I believe DDD has a say in good documentation - classification provides context, context creates boundaries and boundaries lead to intentional implementations (this is where this belongs, rather than it needs to exist).

Code in itself isn't good enough to be considered documentation. The problem in most cases doesn't reside in the fact that the codes' working is commented or not commented, but rather the driving force (domain logic) isn't.

We sometimes forget who's boss - if the code changes, the domain logic or reasoning shouldn't, but if the domain logic or reasoning changes the code definitely will.

Consistency is very important also - convention by itself is useless if it isn't consistent.

Design patterns aren't just 'good practice' - it's lingo us developers should understand. Telling a developer to add a new type to a Factory is better understood than to add a new type to a method (where context and consistency is weak or missing).

Half the struggle is familiarity.

On a side note, API's which seem to favor a lot of documentation are also very domain and context sensitive. Sometimes duplicating functionality isn't evil (same thing, different contexts) and should be treated as separate.

In terms of commenting, it's always good to point out the domain logic behind the reasoning.

For example, you are working in the medical industry. In your method you write "IsPatientSecure = true;"

Now, any decent programmer can figure out that the patient is being marked as secure. But why? What are the implications?

In this case the patient is an inmate that was transferred securely to an off premises hospital. Knowing this, it is easier to imagine the events that lead up to this point (and perhaps what still needs to happen).

Maybe this post seems philosophical at best - but remember that it is 'reasoning' or 'logic' that you are writing about - not code.

share|improve this answer
add comment

I agree with the Papadimouslis quote. The source code can speak for itself, but the code can't tell you why it exists, how it should be used, and how the code should behave.

I don't know a good ratio.

I inherited hundreds of lines of code with very little documentation. It became difficult for me to understand why the code was written. After I found out why the code was written, I had to figure out how to use the code. After I found that out, I had to understand how it is suppose to behave so I can support and maintain the code.

Just from experience, don't make comments too specific or you will end up having to maintain the actual code AND the documentation. It is a nightmare when the documentation and code are out of sync.

share|improve this answer
add comment

Enough to make you stop second guessing yourself.

If at any time during your work you're like "hmm maybe I should document this", go ahead and do it. Then, if you've written some documentation and you're like "maybe I should explain this more", go ahead and do that.

Rinse-repeat until that feeling goes away.

share|improve this answer
-1: You're basically saying 'ehhhh... do whatever you feel like'. Which is a non-answer. –  Steve Evers Oct 6 '10 at 22:47
He appears to be saying 'do whatever you feel is needed' which sounds like a legitimate answer to me. I would be wary of too many more specific answers. –  cjmUK May 28 '12 at 15:38
add comment

I've found that a risk-driven approach such as that presented in George Fairbanks' book Just Enough Software Architecture works extremely well for understanding how much documentation is enough. You can read the section which presents this concept (chapter 3) on his website but the main idea is to:

  • Express the things that worry you about "system understanding" as risks
  • Prioritize the risks
  • Mitigate the risks until your team feels the project risk has been sufficiently reduced. In this case you'll probably be creating some kind of documentation.

To help calibrate concerns so you can prioritize risks I've found it helpful to identify a couple of goals known as the Threshold of Success, that is the minimum set of goals your team thinks a "successful" project must achieve. From a documentation perspective an example ToS might be something like "A developer should be able to build a simple plug-in within 4 hours of picking up the framework for the first time."

Now identify some risks. With the system you've built (or are building) what are the things that worry your team most? Phrase these as risk statements. I like the SEI's condition-consequence style but there are others. Examples:

  • The data model is large and complex; developers might not know which data elements to use in a given situation.
  • The system has API connection limits to increase reliability; developers might accidentally overstep the connection limit.
  • Plug-ins are consumed in several sequential steps; developers might not build plug-ins with these ordered steps in mind.

Now as a team, prioritize the risks. Multi-voting works extremely well.

Mitigate the top priority risks, and repeat starting with identification until the risk of your project failing (defined by the Threshold of Success) is within a tolerable limit. Generally this will mean you'll have some risks that the team agrees are not much of a concern. Keep in mind that you probably won't want to mitigate all the risks. An example mitigation strategy for the last risk above might be to create a tutorial.

share|improve this answer
add comment

As little as possible, but as much as is necessary

I can't remember where & when I first heard that, but it's a maxim with many applications.

The more complex the technology or the application, the more documentation would be needed (obviously), but clearly you don't want to waste time going overboard.

JohnFx's 'hallway test' is sound. But trust yourself; you developed the code, and so you of all people should have a feel for the elements that need extra attention, and the elements that will be obvious to all. Think of the struggles you had developing the code and you'll likely have an idea what another developer will see when they look at your code.

Forget any relationship between effort spent coding and effort spent documenting.

share|improve this answer
add comment

I believe you cannot put this into exact rules. The reason for documenting is to provide the knowledge not easily gathered from the raw code in a form so others can understand and perhaps even maintain said raw code.

Hence the only way you can tell if you have documented enough, is to ask the target audience if it is good enough. I believe the "peer review" process is very good at doing this up front. Notice how much explaining is needed to make your peer understand what you are talking about, and work to minimize that.

If you have never done this before, you cannot estimate how much work it will take, but after a few iterations you will get a much better idea of how much is needed.

share|improve this answer
add comment

Your Answer


