Best way to write a doc project?

Question

How are you going to write API specifications in a doc project. Now there are many ways to write this. But what is the best way to write it so that the reader likes to read it. and its fun to write it.

Something like joel on software.

Answer 1

It is difficult to be prescriptive to do something interesting in order to read and write. However, I would suggest two “levels” of documentation:

• The actual API documentation is at the individual type / method level, which should be very verbose. This may include gotchas, but you should mainly focus on what this particular type / method does.
• The Big Picture documentation that explains the intended use of it. Which idiomatic? What works well? What should i avoid? This is an aspect that is very often missing, in my experience.

Answer 2

Uh ... write how Joel writes? In fact, he even wrote about this:

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

This is good stuff, you should read it.

On the way to concrete advice: in my experience, humor is good. Use metaphors and analogies and drawings, things that help people really understand what code is working. But also include specific details, because you know that someone will want them in the end. (If you do not know this, now you are doing it.)

EDIT: unexpected surprise, Jon Skeet posted a better answer than me ;-) But we are saying the same thing: I completely agree with his second point regarding the documentation of the “larger image”.

Answer 3

I use http://www.balsamiq.com/products/mockups in a story board from API, RIA and many others. Hey, I even use it to show noobs how to make a cup of tea.

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

Answer 4

I am a big fan of auto-generated documentation; when you change your code, the only way to remember to change the document is to insert the document in the code (for example, Javadoc, Doxygen, or something similar in your language).

Nothing prevents us from giving examples ("how to use it") - in fact, it is very important. EventBus Javadoc is a pretty good example of this kind of documentation.

Answer 5

As I answered how to document the headers and implementations of C / C ++ , and after consulting with John Skeet, I write first a general description of the module / class / package that explains the purpose of this device and how it works from a user point of view, and secondly, a description of what each method / function expects as arguments and what it returns to the user. Since I use Doxygen to create my documentation, links between code elements (for example, which methods use this method and which are called by it) are beneficial to me.