Notes from the “The Art of API Documentation” course

For more information on this course, see The Art of API Documentation at Udemy.

2.2 Conceptual material

Overview
- Why
- Requirements
- Key concepts
- Workflow
- Visual information, diagrams,
Getting started
- Lead people through a simple task
- WEB APIs
  - registration
  - get an app key
  - authorization
  - doing something simple
- Platform APIs
  - Downloading SDK
  - Setting up IDE
  - doing something simple
Tutorials
- common tasks
- step-by-step
- screenshots
- start with basic tasks then advanced
Sample code
- short, simple programs that work
- able to copy and modify
- common tasks
- well commented
- different from production code

Important because
- What can the API do?
- What is required to use the API?
- Is it well-designed?
High-level view
Explain why?
- describe key features
- provide a few use cases
Requirements
- WEB APIs
  - usually not required
- Platform APIs
  - programming languages supported?
  - OS, SDKs, IDEs required?
  - versions required?
Key concepts
- write a paragraph or two for each concept. what does the API do?
Architecture
- diagram
- explain major pieces and how they fit together
Workflow
- describe order of tasks
- order of API calls
Diagrams
- architecture diagram
- workflow diagram

Why
- to make the API less intimidating
Hello world
- simplest program that demonstrates feature of API
- TTHW - time to hello world
Structure
- step-by-step instructions
- include lots of screenshots
Web APIs
- registration
- getting app key
- making one or two HTTP requests
Platform APIs
- how to download SDK
- setting up IDE
- creating an app that does a simple task

Guidelines
- prioritize languages
- relevant information grouped together
- clarity over efficiency
Importance
- developers want sample code
- can copy, paste, and modify
Web APIs
- can be called from any language
Platform APIs
- in the language of the SDK
Illustrate workflow
- show a series of API calls
Use hard-coded values
- Never use hard-coded values in production code
- group relevant information together means use hard-coded values in sample code
- exception: app keys and access tokens
plenty of comments
- they are critical
- every class, function, or method should have at least one line
Meaningful names
- variable, class, and member names should be clear
- clarity is more important than efficiency (in sample code)
- long, unwieldy names are fine: they add clarity
- never use meaningless names like “foo”
Object oriented programming
- does not “group relevant information together”