Take the 2-minute tour ×

I need to write out a documentation for developers to be able to use some API web software how should i lay out a documentation? What should always be included? And does it need to be really long or keep it simple and easy as possible for anybody to understand?

share|improve this question



Twitter's api documentation is perhaps the gold standard here. Steal concepts from them. –  Wyatt Barnett Nov 18 '11 at 17:13

3 Answers 3

Describe what each API call does, include a description of any parameters and also what the return value if any is (including possible errors/exceptions).

Additionally if there's time, provide real world examples of how your API is used, if the API is for developers or you are passing it on to someone who will be maintaining the code a nice way to do this is by providing automated unit tests that demonstrate the use of the API and also assert it is working correctly.

share|improve this answer

I believe Einstein's quote, "Everything should be made as simple as possible, but no simpler," applies well here. If you can convey your ideas in 5 pages of text, no reason to write 50.

One way to do this is to setup a wiki site and write documentation in it. Advantage of that is that you can start writing documentation, whatever you miss or stuff that's not clear, other people will be able to correct and add to.

In my team we are also experimenting with using Doxygen. The good part is that it makes you document public interfaces in your code and that's good even without online documentation. But then it generates HTML pages which could contain a description of all your method calls (similar to "Reference" sections in MSDN library).

However, my problem with Doxygen is that often times it feels that "Reference" section is not enough and you want to add MSDN's equivalent "Using" section (and maybe event "About"), but so far I haven't been able to figure out how to do that with Doxygen. And the links it generates are not permalinks so you can't have wiki pages that automatically take you to a specific reference page.

share|improve this answer

There's no really good way to get Doxygen to incorporate the reference docs it creates from code comments into a larger doc set.

You can include pages not in the source tree, but they have to be in the example folder.

In my current project I create a higher-level index and include the doxygen docs as a leaf node from there, ala:

        main index
          /  \
         /    \
       Guide  Ref (from Doxygen)

The bugaboo then becomes how to create a single index with search. I've looked into Wrensoft's Zoom (it uses Php) and it seems to work okay. Another sticking point is allowing comments for feedback. I found some javascript a previous writer used, but it requires inserting a row for every topic/html file into a MySql DB. I see no point in doing that until the docs are quiescent.

share|improve this answer
