views:

56

answers:

4

We're working on a project that requires us to have really easy to use documentation. There is a multitude of posts on Stack Overflow that talk about what makes good documentation, but few about the way it's actually displayed and usability issues.

What projects have good examples of typography and design in their documentation? What is the best way to organise and display documentation?

+2  A: 

I like the jQuery documentation model. Good index, API pages have good examples, community can add comments, available both printed and online.

Telerik does a very nice job as well. They also have many examples to complement the reference style documentation which I think is critical for an API.

Rob
+2  A: 

php has lovely docs. The same goes for MySQL and PostgreSQL.

Apropos your docs, I think it makes sense to treat them like code. Run "tests" (spell checkers, grammar checkers) on them. "Build" them with every release etc. Don't treat it as a second hand citizen.

Make your docs "source" something text based. Restructured Text is nice if you're doing Python and the Sphinx project lets you create really professional looking docs. During the build process, "compile" them into the formats you need (pdf, html, rtf whatever). Don't use binary formats at the outset since it becomes a separate piece and you can't diff, compare them easily.

Noufal Ibrahim
+1  A: 

I like the Apple's approach to documenting APIs and SDK. They read like a book and are easy to read for someone new to the API. Of course, the same can become too verbose for someone already familiar with it, still, I guess, readability of the prose (as compared to aesthetics and usability) will be a top priority. Also, see the Django documentation.

tathagata
A: 

Zenoss has nice docs IMO, http://community.zenoss.org.

aclark