What is the #1 best example of Technical Documentation that you have ever seen? What was it that made it so effective for you?

Question

I am of the opinion that the quality of the documentation of a language (programming language, API, Harware/Technical specification etc) has a direct correlation with the long-term popularity of that language.

Good documentation can not only provide an 'all-in-one desk reference'-type resource for developers but also help to build a community of interested parties around a language. A community which in the future can help to shape and mould the language.

I feel that good documentation must also give a good first impression to someone wishing to start out with the new language and describe in detail how to get started and what issues they may come across in those early stages.

In the hope that language specifications can be improved in the future by this list, I would like to know:

What are the best examples of technical documentation that you have ever seen?

...and, in your opinion, what is it that makes that documentation so good?

Answer 1

For languages, Python's documentation is very easy to use, comprehensive and easy on the eye. Likewise, for frameworks, Django's documentation is very good.

In the Java environment, I've found Spring's documentation to be very good.

In all cases, I think it's because it is written by people with good communication skills and not machine-generated.

Answer 2

K&R. The opposite: Stroustrup's book(s). K&R is well written, great examples, readable font. Stroustrup's book is dense, humorless, dull, and not the least bit inspiring (IMHO). Anything with "Learn X in 21 days" can be assumed to be garbage. Richard Stevens is a great author. Jon Bentley is too.

Answer 3

The perl documentation is hands-down the language winner, IMHO.

It is exhaustive, well-organized, rigorously cross-referential and practical, showing contextualized problem after problem and solution after solution, from "entry-level" solutions to advanced approaches. It's also got a touch of humor, and gives gentle idiomatic advice throughout.

How many SO questions tagged [perl] are rightly and tersely answered, perldoc -f your_question ?

Answer 4

PHP

PHP has a fantastic reference in the form of its website.

The feature I like best is the 'user contributed notes' under each function.

Take for example the reverse array function. Even though the function is simple, there are 11 user contributed notes which can get you started very quickly.

Answer 5

I like java docs.

Answer 6

MSDN

Good structure, good documentation.

Answer 7

The BEST technical documentation I have ever seen resides at msdn.microsoft.com/library. It explicitly spells out platform availability, is grouped mostly logically, and breaks down API to reference [structs, constants, functions], usage and examples all in one. Couple that with a wiki-style ability to flesh out and improve documentation with edge-cases and observed behavior and examples from the real world, and you have an unbeatable combination.

Answer 8

While not "official" documentation per se, "Delphi 4 Unleashed" by Charlie Calvert from back in the 1990s is one of the best programming language reference books I've ever had the pleasure to read. (Maybe it was "Delphi 3 Unleashed". Or both. It's been a while...)

Answer 9

The Qt documentation:

Answer 10

The Apple dev resources are fantastic.

They have great reference docs, as well as guides to give overviews on subject areas and are written in a clear and consistent style. The topics are often written in a generic style so they apply equally to other platforms and languages. The Apple Human Interface Guidelines is an excellent read for all developers.

However, the docs are not perfect. My main criticisms are:

• some of the newer and more obscure classes are not as thoroughly documented as the main classes
• the lack of user contribution (users can provide feedback on the quality of the doc). I guess allowing users to comment on Apples docs isn't the Apple way.

Class references are easy to search for in Google too. The main Cocoa classes all start with NS which is very handy. (Does this count as a legitimate argument against 'proper' namespace systems?)

Answer 11

Symfony PHP Framework

The PHP framework, Symfony, doesn't have great documentation. Their site could do with some work, especially in terms of their function refernce.

However, they have published 2 extremely detailed projects, available as 24 day walk-through sessions.

Each of these starts off with installation/setup tutorials, then goes on to get deep into some of the more tricky and complex features of the framework.

• Symfony 1.0 - The Askeet tutorial
• Symfony 1.2 - The Jobeet tutorial

They have also published several books on the topic which are available to buy OR read online for free. Which is an excellent addition.

Answer 12

ESRI ArcObjects and ESRI Scripting help are definitively great. Documents all aspects of the API and provide examples in different languages (C#, VB.NET and even Java).

Answer 13

What makes for good doc ? A broad question: paper / online, languages / software systems, reference / tutorial, for beginners / for experts ... make for as many different kinds of doc.

A couple of broad criteria:

• overall structure: where are we (author and reader), where's more / less, how can I search the doc ?
• a clear picture of the reader: who's this document for, what level ?

On paper language references:

Imho the C++ reference in Stroustrup (second edition) is very well written. (The language is just too big, a 50-page reference in a 700-page book too much for me -- I lack even a 50-page memory -- but that's another story.)

On Python doc:

I use Python daily (for one-man stuff), but find the language soft and squishy at the core, not clear and solid (example: __new__.) The zillions of Python packages have wildly non-uniform doc quality -- not surprising with zillions of anything and no compass.

A stackoverflow-like feedback system for Python packages and package doc separately would be most useful, would speed up evolution of packages / of doc. (Why hasn't it happened -- entropy ?)

A cookie on doc evolution: "the list of deleted features in this standard is empty" -- Fortran 90.

Pessimism:

Good doc takes time, effort, and a longer timescale than most managers will give you. This may be a universal, print is dying -- look at the doc that comes from legislators and politicians.

On adding tree views, maybe a question to ask separately:

say I have a long long html doc with no tree view (naming no names) but can hack from it a list of (level 1 2 3, key phrase, href) s. How can I generate a tree view from this, to navigate through the doc? Is there an API, examples ? (Whether it runs in a browser with the big html, or separately, is secondary.)

Answer 14

Oh, PostgreSQL docs are really nice too. After you get to know the way things are organized its a piece of cake.