tekom - Europe
Bibliographic Information

DIN A4, 68 Pages, 1. Edition 2018
ISBN 978-3-944449-82-1 (Softcover)

PDF, 68 Pages, 1. Edition 2018
ISBN 978-3-944449-83-8 (E-Book PDF)

Standards and Guidelines for API Documentation

Author(s): Tarnoruder
Publishing Company: tcworld GmbH
  • Software
  • Practical Guides
  • API Documentation

70,00 € (for Members 45,00 €) Softcover, 68 Pages Delivery time: 5-7 working days Status: Available

55,00 € (for Members 35,00 €) E-Book PDF, 68 Pages Delivery time: 2-3 working days Status: Available

97,50 € (for Members 62,50 €) Bundle Softcover & E-Book PDF

Short Description

Creating professional API documentation can be a challenge. Based on widely adopted industry standards, Anne Tarnoruder’s book “Standards and Guidelines for API Documentation” is a valuable source of guidance and education for both technical writers and developers who produce API documentation, covering the major programming API languages and technologies such as Java, JavaScript, MS.Net, REST and OData. This practical guide will prove invaluable in producing excellent API documentation.

About the book

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, resulting in lower-quality documentation. On the other hand, professional technical writers don’t 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, was 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 for the APIs published by the company, and thus increase customer satisfaction with 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, applicable 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 widely used industry standards for these languages and technologies, are more generic rather than specific to SAP and can thus be applied in any company.

  1. Introduction
  2. Terms and Concepts
  3. API Documentation Processes
    1. API Naming Guidelines
    2. Common API Naming Mistakes
    3. API Reference Quality Checklist
  4. Java, JavaScript and MS.NET API Reference Documentation
    1. Documentation Comments
    2. Documentation Tag
    3. Java API Documentation Templates
  5. REST and OData API Reference Documentation
    1. Auto-Generated REST and OData API Reference
    2. Manually Written REST and OData API Reference
  6. Writing Developer Guides
  7. External Resources