Post History

Source: https://writers.stackexchange.com/a/43854
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/43854
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

I would say an API needs reasonable examples of use, and needs attention paid (or links provided) to other closely related elements of the API; even if it is just like "See xyyGraphInit".

You want your programmers to be able to use the product quickly and without having to read the whole dang thing five times. I can (and have had to) read through a list of a hundred routines in an API, and finish that task with hardly a clue of what to do first, or how to get what I wanted.

IMO that is a badly documented API. The API is supposed to help me (the applications programmer) get to the useful things in your product, if your API just explains individual routines and doesn't make it obvious how to make your product actually do work for me, then the documentation is bad.

Most APIs that I have used require several calls to set up and get something done, and many such combinations to accomplish such tasks; for example there may be a hundred types of interactive graphs it can produce.

Other technical writing doesn't necessarily have all these interacting parts and subsets of options and everything else. Code is special in that way, and documentation should provide some guidance on not just the individual routines, but how they are related to each other and how to use them together.

Original score: 3