: Re: What is special in API documentation compared to general technical writing? The title says it all: what is special in Application Programming Interface documentation compared to general technical

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.

Load Full (0)

: Would publishers accept a title which includes the F-word? I have a title for a novel, however, it would lose its zeitgeist if I couldn't include the F-word. I can't go in to details without

@Mendez196

Load Full 1 Comments

: Call her Marie. One way is to let a few other characters (Mike and John) express their frustration with Marie when she is not present; and actually laugh with each other by exaggerating and

@Mendez196

Load Full 0 Comments

: When a writer feels the need to ask others what to write, is that truly a sure sign that they need to change their story to something where they know what to write? No. This is mostly

@Mendez196

Load Full 0 Comments

: Can one be a co-translator of a book, if he does not know the language that the book is translated into? I am translating a religious book from language A to language B and have hired a

: Re: What is special in API documentation compared to general technical writing? The title says it all: what is special in Application Programming Interface documentation compared to general technical

More posts by @Mendez196

: Would publishers accept a title which includes the F-word? I have a title for a novel, however, it would lose its zeitgeist if I couldn't include the F-word. I can't go in to details without

: Call her Marie. One way is to let a few other characters (Mike and John) express their frustration with Marie when she is not present; and actually laugh with each other by exaggerating and

: When a writer feels the need to ask others what to write, is that truly a sure sign that they need to change their story to something where they know what to write? No. This is mostly

: Can one be a co-translator of a book, if he does not know the language that the book is translated into? I am translating a religious book from language A to language B and have hired a

Login to post a comment!

0 Comments

Back to top