Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Much time is wasted to get new developers started with existing software systems, because there is no good documenation. But what makes a system documentation good? One thing is a good API documentation like the Java API doc, but how to transfer the "bigger picture" and other things that cannot be placed in the API doc?

One constraint is that it should not be to hard and time consuming to write the docs, because that is one reason why it is omitted so often.

So, what makes documentation good?


migration rejected from stackoverflow.com Aug 20 at 19:23

This question came from our site for professional and enthusiast programmers. Votes, comments, and answers are locked due to the question being closed here, but it may be eligible for editing and reopening on the site where it originated.

closed as too broad by gnat, Kilian Foth, MichaelT, jwenting, GlenH7 Aug 20 at 19:23

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

possible duplicate of Developer documentation for software application –  Doc Brown Mar 15 '11 at 17:09

5 Answers 5

I always like documentations that have a short overview paragraph with crossreferences (hyperlinks) to other related topics.

Module Xxxx is about Yyyyyy. 
If you are looking for Zzzzzz see ...... 
For an overview .... see ....

This allows me to quickly find the information i am looking for or telling me that the chapter is of no interest for me.

Here on stackechange/stackoverflow i prefer to have a hyperlink that explains what the topic is about.

  1. Code should be properly commented. Code comments should be targeted to the people modifying the code. You should strive for code to show intent, so that you can comment sparingly. You should comment stuff like:
    • Gotchas in libraries you use, explaining why and how are you "workarounding"
    • Optimizations- which by definition are non-obvious (you are optimizing because the obvious code does not perform)
    • if I cut and paste a recipe, I try to refer to the source
  2. apidocs (Javadoc et al.) are required to specify constraints for users of the API and things which are not obvious (i.e. if a method cannot be null, why some exception is thrown, side-effects, etc.)
  3. A quick start guide for libraries. You should provide at least examples that show the usefulness of the library and that show how it's meant to be used
  4. Compilation instructions
  5. A design document, explaining the structure of the code, relevant data structures and patterns
  6. A reference guide. This should be a text book that can be read linearly which should provide all knowledge needed to use your code

Not all points are applicable to all software, of course.


What makes it easy to use .NET Framework (except some dark parts)?

  • The documentation (MSDN) is easy to access, complete, detailed, but not too overloaded with stuff you never need to know,
  • The community (StackOverflow and some forums, including Microsoft ones) can answer most questions,
  • The API is uniform, clear to understand even without documentation, logical (you wouldn't search System.Diagnostics for file I/O methods) and designed by experts.

You see that the documentation is only a part of a whole infrastructure needed to understand some piece of code to be able to reuse it: community and code quality are not less important then good documentation.

In most cases, when you develop a standalone component inside a company a bit smaller than Microsoft, once you have a high quality, refactored code, there are two things which can help for the documentation:

  • Detailed documentation embedded in source code (description of every method with their parameters and return values, summary of every property and every class, etc.)
  • Summary document explaining what is the project, what is it intended about, how it is structured, and what architectural choices were made and why.

With this, it must be pretty easy to start to work with an existing codebase.

Also note that some features of the language can strongly enhance the understanding of your code. Code contracts, as used in .NET Framework, are a good example, since they provide detailed and exact, always up-to-date information about what a method accepts as parameters, and what it returns.

Some bad practices, on the other hand, can make it impossible to work with the codebase. For example, returning error numbers as a return value of a method instead of doing things correctly (using exceptions) have strong chances to make the overall code unclear and difficult to use, even with highly detailed documentation.

"The API is uniform, clear to understand even without documentation, logical (you wouldn't search System.Diagnostics for file I/O methods) and designed by experts." is the BIGGEST reason. I can honestly say I've never read a book on .Net, things just seem to be where I would expect them. And I honestly think MSDN is substandard documentation. It's getting better, but it's still pretty bad. Often has examples that you can't possibly use in production code. –  CaffGeek Mar 18 '11 at 21:23

One idea is to have your new developers work on systems documentation for your more experienced ones. (In many Japanese factory processes, the trainees start by "following" (documenting) the work of experience workers.) This will allow your "newbies" to get "acclimated," while improving themselves and doing some useful work.

It will also provide documentation of varying quality. Some of the trainees will produce better documentation than others (and the same trainees will get better as they go along). Pick out the best examples, then start the NEWEST trainees with those examples. "Wash, rinse, repeat."

  • A documentation which you can find older versions easily. If I'm stuck working with Y framework version 1.3.4 I don't care about the 1.6.5's documentation.
  • Lot of links between pages so I can easily browse it. A good breadcrumb list is always useful.
  • A search box which works.
  • Some working examples to show how whatever is documented can be used.
  • A way for users to comment a page of the documentation.
  • Some "cookbook" examples (like "how to connect a user").
  • Links to related pages at the end of a function / method / class / bundle page à la MAN.

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