Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Documenting an API for the First Time? Quick-Start Tips for Your First API Documentation Assignment

55 views

Published on

If the task to document an API comes earlier than the training and study you feel you need (and it always does!) and you don't know where to start and how to go about it, this presentation will show you not only how to survive your first API documentation gig but also how to turn it into a great learning experience and make a meaningful contribution at that.
The presentation deals mainly with documenting REST APIs, but the approach and the conclusions apply to all kinds of APIs and their documentation.
Presented at the tekom Spring Conference 2019 (Vienna).

Published in: Technology
  • Got a new Iphone 6 in just 7 days completing surveys and offers! Now I'm just a few days away from completing and receiving my samsung tablet! Highly recommended! Definitely the best survey site out there! ♣♣♣ https://tinyurl.com/vd3y33w
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

Documenting an API for the First Time? Quick-Start Tips for Your First API Documentation Assignment

  1. 1. Documenting an API for the First Time? Quick-Start Tips for Your First API Documentation Assignment Petko Mikhailov Content Strategist PROS
  2. 2. REST API BASICS 2 • API definition: A set of rules (interface) that two systems (programs, components, services) agree to follow What are APIs?
  3. 3. REST API BASICS 3 • API definition: A set of rules (interface) that two systems (programs, components, services) agree to follow. • Web API definition: A set of rules (interface) that the systems (programs, components, services) which communicate with the HTTP(S) protocol agree to follow. • RESTful API definition: A set of rules (interface) that two systems (programs, components, services) which communicate with the HTTP(S) protocol using the REST standard agree to follow. What are APIs?
  4. 4. REST API DOCS 4 • TC profession keeps up with technology • TC becomes more technical • TC integrates with development • TC is development • Documentation becomes important • TC can bring value • TC can contribute to the whole development cycle • Require “manual” documentation • A stepping stone into programming For Technical Communicators: What does this mean?
  5. 5. REST OVERVIEW GET Asks the server to retrieve a resource. POST Asks the server to create (and configure) a new resource. PUT Asks the server to edit/update an existing resource. DELETE Asks the server to delete a resource. 5 The four main REST methods
  6. 6. REST OVERVIEW Request and response structures https://evolution-of- tc.com/ https://evolution-of- tc.com/ 66
  7. 7. REST API DOCS 7 • Meant to be consumed not by humans but programs • REST is a style, not a standard • Typically explained by devs • New and inconsistent terminology What makes them difficult: Are APIs difficult to learn?
  8. 8. REST API DOCS 8 • Easier to learn than platform APIs • Only 4 methods • Don’t require knowledge of programming languages • Lots of materials are available What makes them easy: Are APIs difficult to learn?
  9. 9. REST OVERVIEW 9 • The methods • The request • The response • The endpoints • Header and body • The parameters • The data format (JSON, XML) • Authentication • How to pass parameters in the request • How to interpret the response The REST technology in use What do you need to know?
  10. 10. What do you need to know? 10 • REST • The JSON data format • YAML • Postman • cURL • OpenAPI spec • Swagger (and SwaggerHub) • Stoplight • Git (and GitHub) • Markdown • How to build API reference content out of the spec • What makes a good API documentation Tools and technologies
  11. 11. 11 Reference content (“API documentation”) • Endpoint descriptions • Error codes descriptions • Glossary Non-reference content (“user guide”) • API overview • Authentication and authorization requirements • Rate limiting and subscription plans • Getting started / quick start guides • Tutorial • Code samples • SDKs and sample apps • Quick reference • Best practices • FAQ What do you need to know? What API documentation consists of
  12. 12. What do you need to do? 12 • Begin with some introductory material about REST APIs • Complete an online API documentation course • Review some APIs and their documentation • Try using some APIs as a developer • Start building your portfolio • Become a beta tester • Get comfortable with the docs-as-code concept Getting there
  13. 13. What do you need to know? 13 • Documentation source in plain text files • Storing docs in the same repositories as the programming code itself • Collaborating using version control such as git and GitHub • Automating the site build process through static site generator • Versioning docs through git tags/releases Docs-as-code concept
  14. 14. 14 What to do on the job? You are tasked to document an API. Now what?
  15. 15. 15 You are tasked to document an API. Now what? What to do on the job?
  16. 16. 16 •Panic You are tasked to document an API. Now what? What to do on the job?
  17. 17. 17 •Panic •Relax You are tasked to document an API. Now what? What to do on the job?
  18. 18. 18 • No requirement to know a programming language • API docs are badly needed • You are more than welcome - devs don't like to write docs • You are likely to start from a very low level (dev-written docs) • It is structured writing • Devs show understanding • Code examples save the day (and they are provided by the devs). • Same as the other types of TW, you need to know the user. But it's more about playing! • General TW skills do matter • It is structured writing • Process is inherently agile Consider that: What to do on the job?
  19. 19. 19 • Get the “big picture” • Review competitors’ documentation • Start by editing the endpoint and parameter descriptions • Google what you don’t know • Define the minimum viable documentation (MVD) • Work towards creating the MVD • SDK? • Test-use the API yourself. • Provide as many code examples as possible • Ask the “how” and “why” questions • Establish a process for reviewing • Work towards developing the full documentation Surviving your first API documentation assignment What to do on the job?
  20. 20. 20 Minimum Viable Documentation (MVD) • Schemas • Overview • Authentication • Reference • cURL examples Full documentation The MVD, plus: • Getting Started • Tutorials • SDKs and sample apps • Rate limiting and subscription plans • Quick reference • Best practices • API glossary • FAQ What to do on the job? Determine the deliverables • Schemas • Main use case(s)
  21. 21. API Docs Wizardy 21 How to document an API in 10 minutes?
  22. 22. API Docs Resources 22 • Online courses: • Zapier’s API introduction course • SDK Bridge • API the Docs • Tom Johnson’s course • Learn API Documentation with JSON and XML • API marketplaces: • RapidAPI • ProgrammableWeb • Sample API documentation sets: • MailChimp • MailJet • Mailgun • SendGrid Check out these resources
  23. 23. API Docs Resources 23 • Books: • Standards and Guidelines for API Documentation • Tools and Platforms • Postman • Swagger • ReadMe • APIgator • Stoplight • Git, GitHub, and GitHub Pages • Jekyll Check out these resources (continued)

×