Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

What is special in API documentation compared to general technical writing?

+1
−0

The title says it all: what is special in Application Programming Interface documentation compared to general technical writing? What aspects should I take care of?

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/43852. It is licensed under CC BY-SA 3.0.

0 comment threads

3 answers

+1
−0

API stands for "application programming interface". API documentation is addressed to programmers who will use that interface to accomplish some task. While all technical writing is addressed to someone who's trying to accomplish some task, and while some of those people (and tasks) are deeply technical, API documentation has some special considerations:

API reference documentation is essential. Sometimes this is the only documentation you get; sometimes it's accompanied by other doc which I'll get to. For each element (class, REST call, etc), API reference documentation presents the syntax, parameters/arguments/options, return values, restrictions, error conditions, inheritance relationships (if applicable), and a (usually concise) description of what it does. Good API reference documentation includes overviews (for example at the class and package level) as entry points ("how do I use all this stuff together?") and good, focused examples.

API reference documentation is usually generated from comments in the source code, using tools like Javadoc, Doxygen, and Sphinx and following a standard format. For example, here is the top-level page for the Java API, and here is a reference page for a single class.

API documentation includes other elements. Too often it doesn't, but (to continue our Java example), if you go to the top-level page for the Java doc set, you'll see overviews, tutorials, tools, and more. Oracle labels only the reference documentation I described in the previous paragraph as "API documentation", but the Android developer documentation takes a more integrated approach that leads with "build your first app" (tutorial) and "sample code".

Examples are important, and I don't just mean "here's some code". In the Android doc, each entry on the examples page is a link to a GitHub repository containing an introduction that lists requirements, describes the example, and tells the reader where to get help. (It's accompanied by the actual source code.) Example code needs to be clean and well-commented, but it also needs to be presented in a context.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

First of all, let’s make it clear, what API means. API stands for Application Programming Interface. API is a set of tools, communication protocols, and subroutine definitions for building software. Generally speaking, API is a kind of communication channel that allows two separate programs to communicate. How does it work? API is also a part of your daily life. For example, you need to turn on your TV from a distance. You press the ON/OFF button on remote control and the TV turns on. This is how API works. Radio/infrared waves through which a remote control communicates with a TV set act as an API in this case. APIs can be divided into three groups:

  • Software API
  • SCPI (Hardware API)
  • WebAPI

Technical writers develop documentation that includes instructions about how to effectively use a hardware (SCPIs), web-API, or software API. Usually, API documentation contains all the information required to work with the API; it also contains details about classes, functions, arguments, and the like, supported by examples and tutorials. API documentation is usually created by means of regular tools and editors.

More information why this documentation matters is here: What is API Documentation

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/47400. It is licensed under CC BY-SA 3.0.

0 comment threads

+0
−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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »