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.
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.
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...
try block?
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... 
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.
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.
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:
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:
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.
For Java programs there are two things that really make a difference:
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.
