Best way of writing design doc?

Question

How do you go about writing API specs in a design doc. Now there are many ways to write it. But whats the best way to write it so that the reader enjoys reading it.. and its fun to write it.

Something like joel on software.

Answer 1

uh... write the way Joel writes? In fact he's even written about this:

http://www.joelonsoftware.com/articles/fog0000000036.html

It's good stuff, you should read it.

In the way of specific tips: in my experience, humor is good. Use metaphors and analogies and pictures, things that will help people really understand the code works. But include specific details as well because you know somebody will want them eventually. (If you don't know that, now you do.)

EDIT: surprise surprise, Jon Skeet posted a better answer than me ;-) But we're sort of saying the same thing: I completely agree with his second point about "bigger picture" documentation.

Answer 2

It's hard to be prescriptive about making something fun to read and write. However, I would suggest two "levels" of documentation:

• Actual API documentation, at the individual type/method level, which should be very detailed. This can include "gotchas" but should mostly focus on what that particular type/method does.
• "Bigger picture" documentation which explains the intended way of using it. What's idiomatic? What works well? What should you avoid doing? This is the aspect which is very commonly missing, in my experience.

Answer 3

I use http://www.balsamiq.com/products/mockups to story board anything from API, RIA and many other things. Hey i even use it for showing noobs how to make me a cup of tea.

And its an AIR app so you can use it on MAC/PC

Answer 4

I'm a big fan of automatically generated documentation; when you change your code, the only way to not forget to change the doc is to embed the doc in the code (e.g. Javadoc, Doxygen or something similar in your language).

Nothing prevents from putting examples ("how it's intended to be used") there - actually it's quite important. EventBus's Javadoc is a pretty good example of this kind of documentation.

Answer 5

As I answered about how to document C/C++ headers and implementations, and following Jon Skeet advice, I write first a general description of a module/class/package which explains the purpose of this unit and how it works from a user point of view, and second a description of what each method/function expects as arguments and what it returns to the user. As I use Doxygen for generating my documentation, I benefit from links between elements of code (e.g., which methods use this one, and which are called by that one).