Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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
add comment

closed as too broad by gnat, Bart van Ingen Schenau, GlenH7, MichaelT, Dynamic Nov 29 '13 at 4:49

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

3 Answers

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
add comment

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
add comment

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
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.