api documentation best practices
TRANSCRIPT
l All contents Copyright © 2014, MuleSoft Inc.
• API Fanatic
• Open Source Contributor
• Author, Speaker, Consultant
• 10+ years hacking Professional Code
• Dev Relations Manager at MuleSoft
About Me
@mikegstowe
l All contents Copyright © 2014, MuleSoft Inc.
API Documentation is a critical component to the usability of your API – and thus critical to its success
l All contents Copyright © 2014, MuleSoft Inc.
Understanding your users is critical to creating good documentation.
l All contents Copyright © 2014, MuleSoft Inc.5
• Who is your API Documentation for?
- Is it to be used internally∙ Limited technologies?∙ Uniform expertise?
- Is it to be used externally∙ Multiple technologies∙ Wide variety of skill levels
Document with a Purpose
l All contents Copyright © 2014, MuleSoft Inc.6
• Why should they be using your API?
- What functionality does your API provide
• Why shouldn’t they be using your API?
- What are the limitations of your API
Document with a Purpose
l All contents Copyright © 2014, MuleSoft Inc.7
• What are their use cases?
- How are they using your API
- What measures are critical to their success
- What unique workarounds or hiccups might they experience when using that use case
- What are the best practices for that use case
Document with a Purpose
l All contents Copyright © 2014, MuleSoft Inc.8
• How can you create the easiest onboarding process for your users?
- What do they need to get started in 5 minutes
- What are the dependencies or other technologies they need to understand to use your API
- What complications might they face
- What issues might they need to debug
Document with a Purpose
l All contents Copyright © 2014, MuleSoft Inc.
Documentation isn’t about your API… it’s about your users.
l All contents Copyright © 2014, MuleSoft Inc.11
• Who is responsible for maintaining your documentation?
- Do you have technical writers and engineers working on your docs
- Are you using code-first or spec driven development
- What quality measures do you have to ensure your docs and API stay in sync
Have a Plan
l All contents Copyright © 2014, MuleSoft Inc.12
1. API is designed and user tested using RAML
2. Technical Writers modify descriptions in RAML, add in missing doc components
3. Tests are generated from RAML spec
4. Engineers code to tests, API is QA’d
5. Code pushed, RAML pushed to documentation site
Sample Plan Outline when using Spec Driven Development
l All contents Copyright © 2014, MuleSoft Inc.13
• Make it a priority for engineers and technical writers to be communicating throughout the documentation process (including “real-life” documentation QA)
• Make it a priority for engineers to document changes they make as they go
• Make sure technical writers are aware of backward compatibility breaks, format changes
• Hope for the best
If not using Spec Driven Development
l All contents Copyright © 2014, MuleSoft Inc.
Out of sync documentation isn’t only not useful, but detrimental to the usability of your API.
l All contents Copyright © 2014, MuleSoft Inc.17
• Clear, easy path for users to use your API
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.18
• Easy, one click navigation to important information
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.19
• Clear explanations of resource/ method functionality
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.20
• Callouts to important information developers should be aware of (including info boxes, alerts, and warnings)
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.21
• List of available parameters for the method, including description, whether or not it is required, default value, example value, and any pattern or format requirements.
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.22
• Sample calls with the correlating content types (ie what the call looks like when using JSON, XML, etc)
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.23
• Sample responses for each content type
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.24
• Code examples for the languages most commonly used by your users (ie a public API might showcase JavaScript, PHP, Ruby, Java, and .NET)
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.25
• Sample use-case/ walk-though of the API method
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.26
• Ability to try API calls in real-time/ interactive API debugging
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.27
• List of error HTTP status codes and reason(s) that code may be returned
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.28
• Or if you use custom error codes (ie an error code within the body of the error response)
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.29
• Information on/ links to appropriate SDKs/ code libraries
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.30
• Frequently Asked Questions with answers (including code examples or links to tutorials)
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.31
• Links to additional resources/ learning tools
• Comments section for group discussion
• Links to support mechanisms (forum, knowledge base, contact form, etc)
Good Documentation Provides:
l All contents Copyright © 2014, MuleSoft Inc.
Your documentation should be so easy to use that a developer with no experience can implement your API in less than 5 minutes.
l All contents Copyright © 2014, MuleSoft Inc.33
• Shopify
• Spotify
• Constant Contact
• Twilio
• Stripe
• SendGrid
• DropBox
• MuleSoft Champions
Examples of Great API Documentation
l All contents Copyright © 2014, MuleSoft Inc.34
• mulesoft.com/restbook – book on API design and documentation (presentation from Chapter 12)
• Idratherbewriting.com – technical writing blog
• bit.ly/raml4doc – presentation on using RAML for documentation
• bit.ly/githubmd – GitHub’s guide to markdown (used for Anypoint Platform documentation)
More Resources