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?
- Anybody can ask a question
- Anybody can answer
- The best answers are voted up and rise to the top
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.
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.
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.
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: