An API writer is a

technical writer A technical writer is a professional information communicator whose task is to transfer information between two or more parties, through any medium that best facilitates the transfer and comprehension of the information. Technical writers researc ...

who writes documents that describe an application programming interface (API). The primary audience includes programmers, developers, system architects, and system designers.

Overview

An API is a

library A library is a collection of materials, books or media that are accessible for use and not just for display purposes. A library provides physical (hard copies) or digital access (soft copies) materials, and may be a physical location or a vir ...

consisting of interfaces, functions, classes, structures, enumerations, etc. for building a software application. It is used by developers to interact with and extend the software. An API for a given

programming language A programming language is a system of notation for writing computer programs. Most programming languages are text-based formal languages, but they may also be graphical. They are a kind of computer language. The description of a programming ...

or system may consist of system-defined and user-defined constructs. As the number and complexity of these constructs increases, it becomes very tedious for developers to remember all of the functions and the parameters defined. Hence, the API writers play a key role in building

software Software is a set of computer programs and associated software documentation, documentation and data (computing), data. This is in contrast to Computer hardware, hardware, from which the system is built and which actually performs the work. ...

applications. Due to the technical subject matter, API writers must understand application

source code In computing, source code, or simply code, is any collection of code, with or without comments, written using a human-readable programming language, usually as plain text. The source code of a program is specially designed to facilitate the w ...

enough to extract the information that API documents require. API writers often use tooling that extracts

software documentation Software documentation is written text or illustration that accompanies computer software or is embedded in the source code. The documentation either explains how the software operates or how to use it, and may mean different things to people in ...

placed by programmers in the source code in a structured manner, preserving the relationships between the comments and the programming constructs they document. API writers must also understand the software product and document the new features or changes as part of the new software release. The schedule of software releases varies from organization to organization. API writers need to understand the software life cycle well and integrate themselves into the

systems development life cycle In systems engineering, information systems and software engineering, the systems development life cycle (SDLC), also referred to as the application development life cycle, is a process for planning, creating, testing, and deploying an informa ...

(SDLC). API writers in the

United States The United States of America (U.S.A. or USA), commonly known as the United States (U.S. or US) or America, is a country primarily located in North America. It consists of 50 states, a federal district, five major unincorporated territori ...

generally follow ''

The Chicago Manual of Style ''The Chicago Manual of Style'' (abbreviated in writing as ''CMOS'' or ''CMS'', or sometimes as ''Chicago'') is a style guide for American English published since 1906 by the University of Chicago Press. Its 17 editions have prescribed writi ...

'' for

grammar In linguistics, the grammar of a natural language is its set of structural constraints on speakers' or writers' composition of clauses, phrases, and words. The term can also refer to the study of such constraints, a field that includes domain ...

and

punctuation Punctuation (or sometimes interpunction) is the use of spacing, conventional signs (called punctuation marks), and certain typographical devices as aids to the understanding and correct reading of written text, whether read silently or aloud. An ...

Qualifications

API writers typically possess a mix of programming and language skills; many API writers have backgrounds in programming or

technical writing Technical writing is writing or drafting technical communication used in technical and occupational fields, such as computer hardware and software, architecture, engineering, chemistry, aeronautics, robotics, finance, medical, consumer electronics, ...

. *

Computer programming Computer programming is the process of performing a particular computation (or more generally, accomplishing a specific computing result), usually by designing and building an executable computer program. Programming involves tasks such as anal ...

background (Knowledge of C,

C++ C++ (pronounced "C plus plus") is a high-level general-purpose programming language created by Danish computer scientist Bjarne Stroustrup as an extension of the C programming language, or "C with Classes". The language has expanded significan ...

Java Java (; id, Jawa, ; jv, ꦗꦮ; su, ) is one of the Greater Sunda Islands in Indonesia. It is bordered by the Indian Ocean to the south and the Java Sea to the north. With a population of 151.6 million people, Java is the world's mos ...

PHP PHP is a general-purpose scripting language geared toward web development. It was originally created by Danish-Canadian programmer Rasmus Lerdorf in 1993 and released in 1995. The PHP reference implementation is now produced by The PHP Group. ...

, or other

s) *Knowledge of formatting standards like

Doxygen Doxygen ( ) is a documentation generator and static analysis tool for software source trees. When used as a documentation generator, Doxygen extracts information from specially-formatted comments within the code. When used for analysis, Doxyge ...

Javadoc Javadoc (originally cased JavaDoc) is a documentation generator created by Sun Microsystems for the Java language (now owned by Oracle Corporation) for generating API documentation in HTML format from Java source code. The HTML format is used for ...

, OpenAPI, or DITA *Knowledge of editors and tools, like FrameMaker *Excellent communication and writing skills to interact with developers Expert API/

software development kit A software development kit (SDK) is a collection of software development tools in one installable package. They facilitate the creation of applications by having a compiler, debugger and sometimes a software framework. They are normally specific ...

(SDK) writers can easily become programming writers.

API writing process

The API writing process is typically split between analyzing and understanding the

, planning, writing, and reviewing. It is often the case that the analytical, planning, and writing stages do not occur in a strictly linear fashion. The writing and evaluation criteria vary between organizations. Some of the most effective API documents are written by those who are adequately capable of understanding the workings of a particular application, so that they can relate the software to the users or the various component constructs to the overall purpose of the program. API writers may also be responsible for authoring

end-user In product development, an end user (sometimes end-user) is a person who ultimately uses or is intended to ultimately use a product. The end user stands in contrast to users who support or maintain the product, such as sysops, system administrato ...

product documentation. While reference documentation may be auto-generated to ensure completeness, documentation that helps developers get started should be written by a professional API writer and reviewed by subject matter experts. This helps ensure that developers understand key concepts and can get started quickly.

Product

API writers produce documents that include: *API reference guides *Programmers' guides *Developer manuals *Administration manuals *Installation guides *Implementation and integration guides

References

{{Reflist Application programming interfaces Software documentation

Overview

Qualifications

API writing process

Product

See also

References