I need to write documentation for several projects I worked on. I was wondering what, according to your experience, makes documentation useful and complete. What part should I include, how deep should I go in my explanation, etc?

My target audience is developers. The purpose of the documentation is to make it easy to update or finish projects.


12 Answers 12


I like examples. If you have an API that performs a variety of foo operations on bar objects, include practical examples, not just a single line showing how to call the function.

Also make sure you include somewhere a high-level "big picture" overview of whatever is being documented. It's great to know the different types of foo operations available, but it's also good to know why there are different variations, and some guides as to know when to use which variant.

For some systems, a brief developer-centric user manual is also good. This is important if new developers don't even know to use the existing parts of the project.

A setup guide for building and compiling is also very important if the setup is non-trivial (more than just add files to IDE project and click "compile"). This may include database connections, and server configuration.

  • 4
    You can write unit tests which simultaneously serve as the samples. Apr 7 '11 at 18:26
  • @Steven Jeuris: That's a good one, I'll consider that next time I have to write documentation. Apr 7 '11 at 18:28
  • unit tests are guaranteed to be up to date as opposed to cut-and-paste sections in documentation.
    – user1249
    Apr 11 '11 at 9:22

I want to know why.

Documentation, whether comments or a Word file, should not make the code redundant. I know what the code does - it's right there for me to read. I want to know why...

  • It exists. What purpose does it fulfill?
  • It was written that way. Was it just the first way that came into your head, or is there a good reason for that ugly try block?
  • It was designed that way. If you made a class that allows communication with legacy code, but makes no sense if legacy didn't exist, I want to know that before I go, "What was this idiot thinking?"

Since I've seen only one minor mention: Screenshots!

Even for CLI-only tools, it can help to solidify certain concepts. A method I employ is capturing the whole window with a bit of background. Then I'll change the background for subsequent shots. It helps to distinguish the images, especially for people coming back to reference. See, e.g... example

Also, screencasts! It's great to have reference material in text, but when you're first getting into a tool it's even better to have someone familiar with it step you through the basics of the interface.


Step by Step how-to guides.

On a wiki preferably, so they can be changed as soon as something needs updating.


The purpose of the documentation is to make it easy [for developers] to update or finish projects

Then good documentation achieves that purpose.

To make good documentation, get some information from people who will be using your documentation.

Question 1. What can't they do now? Why are they unable to update or finish a project?

Collect answers to the question from everyone involved. Stakeholders and non-stakeholders.

Once you have some reasons, you have to find causes for those reasons.

Question 2. What prevents them from updating or finishing a project?

Collect answers to the question from everyone involved.

Once have have root causes, you have to get some solutions to those problems.

Question 3. What changes would help update or finish a project?

Ideally, the answer to this question is "more information, specifically..."

If so, that's what your documentation will include, the specific information required. Question 3 tells you specifically what makes good documentation.

If, on the other hand, information isn't the solution, stop writing documentation. Keep digging into cause and effect and solve the problem.

  • State the objective (purpose) of the documentation at the beginning.
  • Include a table of contents if the documentation spans several pages.
  • Be as specific as possible when writing things down.
  • Everything in your head should be on paper.
  • Include figures and screenshots where appropriate as they visualize what you are writing about.

You will know if the documentation is good if after several months you need to read it again and you can understand everything that you wrote down and that it makes sense.

  • "Everything in your head should be on paper" - that sounds like a dangerous requirement ;)
    – pdr
    Apr 7 '11 at 16:49
  • 2
    @pdr: Really good point. I've read the worst rambling brain-dumps from people who (a) believe that everything needs to be written (b) can't focus and (c) believe that if it's not written in a single document it will somehow vanish. A second document seems anathema to some folks. Focus is important. Goals are important.
    – S.Lott
    Apr 7 '11 at 17:15

Examples should be must. And from my point of view(as a student), the person who is seeing your document should not search a lot.

Your document should be in good hierarchy , so that getting an information is really easy :)


Test documentation just like a usability test. Give the document to a user with no explanation and watch over their shoulder to see if they get any value out of it. Hopefully it meets your objective.


Use an iterative approach to writing documentation. Once you've written up a basic set of instructions, do the following:

  1. Give the document to a user. Ask them to use it to perform the task.
  2. Note any questions or problems they encounter.
  3. Edit the document to address the questions or problems.
  4. Repeat.

You're done when your user has no more questions or problems.


Write tests.

What I most want when I take over a project is a good set of automated tests. By good, I mean:

  • They all run,
  • They are clearly written,
  • They convey both they why and the what, and
  • They are more or less comprehensive.

I like tests better than regular docs because a computer can verify that they still apply. Basically, tests are executable documentation.

On top of that, I'd like a 1-3 page document on the system architecture, plus a well-organized and well-named code base.

  • 1
    I used to not believe this, but I've been looking at several open source projects recently, and the tests were by far the most useful examples for me. +1!
    – Peter K.
    Apr 11 '11 at 1:25

For Java programs there are two things that really make a difference:

  • Functional unit tests showing how the code is to be used. For code developed with test-driven design this essentially is the specification in runnable form.
  • javadoc - i.e. the embedded HTML snippets which end up in http://download.oracle.com/javase/6/docs/api/ except for your code.

Well done, these two together can account for - IMHO - around 90% of the documentation.


To throw in something from the last century which has become almost a dead art:

A good index. By that I mean key reference emboldened, further (relevant) references and further information / examples sub-listed. Examples picked out. Multiple references to varying uses and synonyms. Accurate page numbers (or links). Most tech books completely fail on this these days. (I'm amazed no one has mentioned indexes yet)

Thinking from an API doc perspective, good cross referencing to alternative calls and why you might want them. "Trying to print a graphic? You probably need gfxPrint not Print, see pp 888" etc.

Makes learning go so much faster when you're past the worked examples and wanting to fly alone - 10 mins of google every api call isn't helpful.

JFGI or a search box isn't enough as that will get 80% irrelevant references to the API and so often doesn't easily pick up the right reference or the case you're googling the wrong one.

Not the answer you're looking for? Browse other questions tagged or ask your own question.