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?

share|improve this question
    
possible duplicate of Developer documentation for software application –  Doc Brown Mar 15 '11 at 17:09
add comment

migrated from stackoverflow.com Mar 15 '11 at 22:22

This question came from our site for professional and enthusiast programmers.

6 Answers

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.

share|improve this answer
add comment
  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.

share|improve this answer
add comment

I just saw Armin Ronachers presentation on Flask during PyCon 2011. He emphasized the documentation. Some points he made (which may specific to the Flask project):

  • Make your documentation look good, e.g. Flask docs are B/W; use a readable font; the process of compiling the documentation is streamlined. In short: You'll want to see how good your docs look like to stay motivated to write more of it.

  • Flask is a microframework (~ 1KSLOC), yet it's documentation spans around 200 A4-pages currently; every major design decision is explained; lots of example code. Also the community feeds the documentation process with their questions, etc.

  • Some open-source projects miss the key point of good docs; they may have a very useful library buried under outdated, cryptic docs, which might repel potential users.

share|improve this answer
add comment

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.

share|improve this answer
    
"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
add comment

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."

share|improve this answer
add comment
  • 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.
share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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