Wir machen Sie darauf aufmerksam, dass unsere Website über Cookies personenbezogene Daten von Ihnen erhebt. Mehr Informationen Zustimmen und fortfahren

2018

Practical Guides

Standards and Guidelines for API Documentation

Anne Tarnoruder

Die Erstellung professioneller API-Dokumentationen kann eine Herausforderung sein. Anne Tarnoruders Publikation 'Standards and Guidelines for API Documentation' ist eine wertvolle Orientierungshilfe und dient zur Weiterbildung sowohl von Technischen Redakteuren als auch von Softwareentwicklern, die API-Dokumentationen erstellen, sowie von Informationsarchitekten. Diese Richtlinien, die die wichtigsten API-Programmiersprachen und -technologien wie Java, JavaScript, MS.Net, REST und OData abdecken und auf den weit verbreiteten Industriestandards basieren, dienen als umfassende Wissensquelle für die API-Dokumentation.

Aufbau des Praxisleitfadens

In der schnell wachsenden API-Ökonomie erweitern Softwareanbieter ihr Angebot an Entwicklungsplattformen, -tools und -APIs. Die professionelle API-Dokumentation ist ein wichtiger Faktor bei der Akzeptanz dieser Angebote. Verschiedene Unternehmen und Tool-Anbieter definieren und pflegen ihre eigenen Regeln und Best Practices für die Dokumentation von APIs, aber bisher gibt es keinen umfassenden, weit verbreiteten Industriestandard in diesem Bereich. Darüber hinaus kommt der API-Dokumentation keine besondere Aufmerksamkeit zu. Sie wird oft von Softwareentwicklern geschrieben, die jedoch oft nicht über genügend Ressourcen und professionelle Schreibfähigkeiten verfügen, was häufig zu einer schlechteren Dokumentationsqualität führen kann. Auf der anderen Seite verfügen professionelle Technische Redakteure nicht immer über die besonderen Kenntnisse und Fertigkeiten, die für den Umgang mit diesen Themen erforderlich sind.

Um diese Lücken zu schließen, wurde 2014 eine Gruppe von API-Dokumentationsexperten bei SAP unter der Leitung von Anne Tarnoruder gebildet, die ein unternehmensweites Paket von Standards, Richtlinien und Best Practices erarbeiten sollte. Ziel dieser Standards und Richtlinien (S&G) ist es, ein höheres Maß an Qualität und Benutzerfreundlichkeit der vom Unternehmen veröffentlichten APIs zu erreichen und damit die Kundenzufriedenheit und Akzeptanz der APIs zu erhöhen.

Die S&G werden seither SAP-weit als Orientierungs- und Schulungshilfe sowohl für Autoren als auch für Entwickler, die API-Dokumentationen erstellen, eingesetzt. Die S&G deckt sowohl automatisch generierte als auch manuell geschriebene API-Referenzdokumentationen ab und gilt für die wichtigsten API-Sprachen und -Technologien wie Java, JavaScript, MS.Net, REST und OData. Diese ursprünglich für SAP geschriebenen Richtlinien, die auf den weit verbreiteten Industriestandards für diese Sprachen und Technologien basieren, sind eher generischer Natur als SAP-spezifisch und können in jedem Unternehmen angewendet werden.

Inhalt des Leitfaden

 

  • Allgemeine Hintergrundinformationen zu APIs, Begriffen und Konzepten.
  • Prozesse und Best Practices für die Co-Autorisierung der API-Dokumentation durch den Technischen Redakteur und Entwickler.
  • Standardbenennungskonventionen und -richtlinien für die gemeinsamen API-Elemente, wie z.B. Packages, Interfaces, Klassen, Methoden.
  • Schreiben von Konventionen und Richtlinien für API-Beschreibungen, veranschaulicht anhand von Beispielen.
  • Java-API-Dokumentationstemplates für die Javadoc-Generierung.
  • Formatierungsregeln und Standard-Tags, die mit den Generierungstools wie Javadocs, Doxygen, JSDocs und Swagger/OpenAPI kompatibel sind.
  • Vorlagen für die manuelle Dokumentation von REST/ODaten-APIs.
  • Allgemeine Richtlinien für das Verfassen hilfreicher Entwicklerleitfäden.

Inhaltsverzeichnis

    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

Die Autorin

Anne Tarnoruder ist eine erfahrene technische Redakteurin mit einem starken Hintergrund im Bereich Software-Engineering. Vor Beginn ihrer Laufbahn als Technische Redakteurin im Jahr 2004 war sie in verschiedenen Positionen als Softwareentwicklerin, Teamleiterin und Systemarchitektin in israelischen High-Tech-Firmen tätig.
Dadurch konzentriert sich Anne Tarnoruder auf die Dokumentation für Softwareentwickler, APIs und SDKs. Sie ist regelmäßige Referentin auf lokalen und internationalen Tagungen im Bereich Technische Kommunikation (MEGAComm, tekom) zu API-bezogenen Themen.
Anne Tarnoruder hat einen Master-Abschluss in Angewandter Mathematik.

Danksagungen

An Frederic Moitel und Ray Lefuel, den Hauptbeiträgen zu den Kapiteln Java, JavaScript und MS.NET API Referenzdokumentationen.

An Michelle Kemp, Jack Schueler, Malca Sagal, Raylene Mehl, Nicole Goldman, Daniel Wroblewski, Vadim Tomnikov, Trevor Holdsworth, Steffen Lutter, Frederic Rousseau, G S, Sreedhara und an alle anderen SAP-Kollegen, die durch die Durchsicht der Materialien, ihr Feedback und ihre Unterstützung zum Entstehen dieser Publikation beigetragen haben.

Bibliografische Informationen

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)

Publikation kaufen

Diese Publikation können Sie ab sofort in der tekom-Geschäftsstelle vorbestellen. Verwenden Sie dazu bitte unser Fax-Bestellformular (Fax an 0711 65704-99) oder schreiben Sie uns eine E-Mail an info(at)tekom.de.

  • Softcover: 70,00 EUR (für tekom-Mitglieder: 45,00 EUR)
  • E-Book PDF: 55,00 EUR (für tekom-Mitglieder: 35,00 EUR)

Alle Preise inklusive gesetzlicher Mehrwertsteuer, zzgl. Porto und Versand.

Wichtig bei Bestellung des E-Book PDF: Bitte bestätigen Sie bei Ihrer Bestellung, dass Sie mit den Content-Lizenzbedingungen einverstanden sind.

Publikation gleich hier bestellen:

Bestellformular für tekom-Publikationen

Lizenzvereinbarung elektronischer Medien

allgemein