API writer
 | This article includes a list of references, related reading, or external links, but its sources remain unclear because it lacks inline citations. (April 2009) |
 | This article may require copy editing for grammar, style, cohesion, tone, or spelling. (December 2008) |
 | This article is currently undergoing a major edit by the Guild of Copy Editors. As a courtesy, please do not edit this page while this message is displayed. The copy editor who added this notice is listed in the page history. This page was last revised at 04:39, 21 July 2010 (UTC) (14 years ago) by Paulmnguyen (talk · contribs) (). Please remove {{GOCEinuse}} from this page as this page has not been edited for at least 24 hours. If you have any questions or concerns, please direct them to the Guild of Copy Editors' talk page. Thank you for your patience. |
An API writer is a technical writer 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 basic library consisting of interfaces, functions, classes, structures, enumerations, etc. for building a software application. It is used by development teams to interact with and extend the software. An API for a given programming language and 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 applications.
Due to the technical subject matter, API writers must understand application source code enough to extract the information that API documents require. Some common tools used by API writers include computer software that extracts documentation placed by programmers in the source code in a structured manner, preserving the relationships between those comments and the programming constructs they document.
API writers must also understand the software platform/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. The writers need to understand the software life cycle well and integrate themselves into the Systems Development Life Cycle.
API writers in the United States of America generally follow The Chicago Manual of Style for grammar and punctuation.
Product
API writers produce documents that include:
- API Reference Guides
- Programmers' Guides
- Developer Manuals
- Administration Manuals
- Installation Guides
API technical process
This is one of the most important challenges faced by technical writers or whoever is interested in moving to API documentation. The writing and evaluation criteria varies between organizations. It is usually most beneficial for API writers to possess a broad and thorough knowledge of programming structure and syntax, while also being adequately capable of understanding the workings of a particular given application with a greater level of detail related to the specific classes or interfaces from which its usefulness derives.
60% of the tasks encountered in the writing process involve analyzing, planning, and understanding the code/functions, while the remaining 40% of time would typically be spent actually writing and reviewing implementations. Hence, a very solid understanding of the process is of key importance to API writers as they frequent between planning and implementation phases. A good foundation of a variety of programming skills is well complemented by an ability to communicate effectively, especially when the writer seeks to develop a fluent level of understanding with developers. Finally, API writers may also be at least partly responsible for authoring product documentation outlining and specifying things like included program content, methods of implementation, and many other relevant details.
Qualifications
Usually, API writers possess a mix of programming and language abilities. It’s good to have programming background but again it’s not mandatory. Many API writers switch from programming or technical writing.
- Programming background (Knowledge of C, C++, Java, Assembly, etc.)
- Knowledge of tools like Doxygen, Javadoc, or FrameMaker
- Excellent communication and writing skills to interact with developers
Expert API/SDK writers can easily become programming writers.
Resources
- API Writing Blog
- Yesterday API was just another acronym
- API Documentation
- Introduction to API documentation
- What is API Documentation
- AllWrite Design Blog
Books
See also
- Application programming interface (API)
- Software documentation
- Technical writer
- Technical communication
- Technical communication tools
- Comparison of documentation generators
External links
- Technical writing
- Free Wikiversity Technical Writing Courses
- Docsymmetry
- Free online guide to breaking into Technical Writing as a career
- EServer Technical Communication (and Technical Writing) Library
- FCH Communications: What is Technical Writing?
- The Institute of Scientific and Technical Communicators - UK and International Association for Technical Writers
- Technical Communicator's Association of New Zealand
- The Death of the Technical Author?
- Writing User Manuals from the Middle Out
- Usability Professional's Association of New Zealand
- Keycontent.org: Online community devoted to discussion of content development, technical communication, and related disciplines
- DITA Users - a member organization helping people get started with topic-based structured writing.
- Different section where technical writing is needed
- TechTact.org Technical and Tactful writing