We hereby notify you that our website collects personal data from you using cookies. more information Agree and continue

2018

NEW Practical Guides

Standards and Guidelines for API Documentation

Anne Tarnoruder

Creating professional API documentation can be a challenge. 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, and based on the widely adopted industry standards, these guidelines serve as a vast source of knowledge about API documentation.

About this Practical Guide

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.

Content

 

  • General background information on APIs, terms and concepts.
  • Processes and best practices for coauthoring API documentation by technical writer and developer.
  • Standard naming conventions and guidelines for the common API elements, such as packages, interfaces, classes, methods.
  • Writing conventions and guidelines for API descriptions, illustrated by examples.
  • Java API documentation templates for Javadoc generation.
  • Formatting rules and standard tags compatible with the generation tools, such as Javadocs, Doxygen, JSDocs, and Swagger/OpenAPI.
  • Templates for manual documentation of REST/OData APIs.
  • General guidelines for writing helpful developer guides.

Table of Contents

    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

Bibliographic Data

Standards and Guidelines for API Documentation
DIN A4, 68 pages, 2018, english
ISBN 978-3-944449-82-1 (softcover)
ISBN 978-3-944449-83-8 (ebook PDF)

The Author
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.

Credits
To Frederic Moitel and Ray Lefuel, the key contributors to the Java, JavaScript and MS.NET API Reference Documentation chapters.
To Michelle Kemp, Jack Schueler, Malca Sagal, Raylene Mehl, Nicole Goldman, Daniel Wroblewski, Vadim Tomnikov, Trevor Holdsworth, Steffen Lutter, Frederic Rousseau, G S, Sreedhara, and all other SAP colleagues who contributed by reviewing the materials, providing their feedback and support.

Buy This Publication

Please use our fax order form for your order and either send us a fax at +49 711 65704-99 or email us at info(at)tekom.de

  • softcover: 70.00 EUR (for tekom members: 45.00 EUR)
  • ebook PDF: 55.00 EUR (for tekom members: 35.00 EUR)

All prices include VAT. Shipping and handling are additional.

The eBook PDF version includes a content license. You must agree in writing to the Opens internal link in current windowcontent license conditions upon ordering.