Standards and Guidelines for API Documentation

For Technical Writers, Software Developers, Information and Software Architects
1. Auflage 2018
ISBN: 978-3-944449-82-1
Verlag: tcworld

Buch, Englisch, 66 Seiten, Format (B × H): 210 mm x 297 mm, Gewicht: 229 g

Reihe: Practical Guides

In the rapidly expanding API economy, software vendors are expanding their offerings of development platforms, tools and APIs. Professional API documentation is a key facilitating factor in the adoption of these offerings. Various companies and tool vendors define and maintain their own rules and best practices for documenting APIs, but so far there is no comprehensive widely adopted industry standard in this area. Furthermore, API documentation tends to fall between the cracks. It is often written by developers who don’t have enough resources and professional writing skills, which leads to the lower quality of documentation. On the other hand, professional technical writers do not always have the special knowledge and skills required to handle these topics.
To address these gaps, a group of API documentation experts at SAP, led by Anne Tarnoruder, had been formed in 2014 to produce a company-wide set of standards, guidelines and best practices. These Standards and Guidelines (S&G) aim to reach a higher level of quality and usability of the APIs published by the company, and thus increase the customer satisfaction and acceptance of APIs.
The S&G have since been used across SAP as a source of guidance and education for both writers and developers who produce API documentation. The S&G cover both auto-generated and manually written API reference documentation, and apply to the major API languages and technologies, such as Java, JavaScript, MS.Net, REST and OData. Though originally written for SAP, these guidelines, based on the widely used industry standards for these languages and technologies, are more of a generic nature than specific to SAP and can be applied in any company.

Zielgruppe

Technical Writers, Software Developers, Information and Software Architects
Technische Redakteure, Softwareentwickler, Informations- und Softwarearchitekten

Autoren/Hrsg.

Tarnoruder, Anne

Über Autor(innen)

Tarnoruder, Anne
Anne Tarnoruder is an experienced technical communicator with a strong background in software engineering. Prior to starting her technical writing career in 2004, she held various positions of a software developer, team lead and system architect in Israeli high-tech companies.
Leveraging her background, Anne is focusing on documentation for developers, APIs and SDKs. She is a frequent speaker at the local and international tech communication conferences (MEGAComm, tekom) on API-related topics.
Anne holds a M.Sc. in Applied Mathematics.