Activity 6a: Judge conceptual content and decide which is best
Evaluate why — use inductive reasoning
Product overview
Addressing the "why"
"Startups fail when they are not solving a market problem. We were not solving a large enough problem that we could universally serve with a scalable solution. We had great technology, great data ..., great reputation as a thought leader, great expertise, great advisors, etc, but what we didn’t have was technology or business model that solved a pain point in a scalable way." — Treehouse Logic, The Top 20 Reasons Startups Fail
Example 1: Spotify
Example 2: Hootsuite
Example 3: Watson Assistant
Key principles
Don't assume everyone already knows the who, what, why, where, and how of your API
Provide high-level details about workflows, authentication, endpoints, etc.
Link to your Getting Started topic
API getting started
Compare with Hello World tutorials
Example 1: Mailchimp
Example 2: Paypal
Example 3: Google
Key principles
Define the simplest possible end-to-end steps to get started — link out to more details
Simplify account setup or other required assets or configurations
Tip: Use Run in Postman
API authentication and authorization
API Key
HMAC
OAuth
Example 1: Sendgrid
Example 2: Twitter
Example 3: AWS
Key principles
Don't include unnecessary details about how the authorization works
Provide a code sample
Describe correct usage — such as public versus private tokens in client-side code
API status and error codes
Response header in curl
curl -I -X GET 'https://api.openweathermap.org/data/2.5/weather?zip=95050&units=imperial&appid=APIKEY'
Provide an at-a-glance experience to help users understand the whole
Link the quick reference to the full details
SDKs (Software Development Kits)
Example 1: SAP SDKs
Example 2: Paypal SDKs
Example 3: Facebook SDKs
Key principles with SDKs
Explain how to integrate the SDK
Assume audience is familiar with language
Explain how to get the sample app working
Questions?
Conceptual content in API docs By Tom Johnson / @tomjohnson idratherbewriting.com Slides available at idratherbewriting.com/slides/conceptual_content_api_docs.html Not sure what to call this info: Conceptual information, Tutorials, How-to guides, Programming guides, Administratrive information, Developer portal, User guide, Guides if there are divisions of responsibilities, tech writers typically handle this type of content more there's a whole lot of other topics related to APIs that i won't cover, so see the other presentations for that.