A presentation at Australian Society for Technical Communication Annual Conference 2018 in in Gold Coast QLD, Australia by Alec Clews
Document the API Alec Clews ASTC Annual Conference October 2018 Slides at https://tinyurl.com/alecthegeek-api-docs
Agenda ● What are APIs and why should I care? ● What's different about API docs? ● How should API docs be structured? High level content plan ● Some important messages on content and reference material ● What tools do I need?
Who is Alec? Old school software nerd Consulting, docs, code, testing, support, speaking, ... Works as the technical integration manager at PaperCut Software "The API guy" "Developer Relations" or "Developer Evangelism" Loves technology, sometimes too much! and beer and coffee... @alecthegeek alecthegeek https://www.linkedin.com/in/alecclews/
Who needs API docs? ● Second and Third Party Developers: ○ Customers ○ Business Partners ○ Independent software vendors ○ Other teams in your organisation (but we'll ignore them)
& why are API docs important? ● ● They will help your product or service be more successful. For example ○ Uber taxi application integrates with Google Maps ○ Re-Leased Property Mgt Software integrates with Xero If they get stuck they'll either ○ Not bother to use your product ○ Call your support desk
How do APIs enable success? ● No software exists in isolation ○ Customers and partners can integrate your system with other systems ● Extend the value of your product ○ Third parties can deliver solutions you can't ○ Pushing your brand into new markets ● Your ecosystem becomes deeply engaged with you and your product ● Your brand is supported with a quality API programme delivery
Application Programming Interface ● Contract between two pieces of software a.k.a specification ○ What can the client request? ○ What will the server do? ○ What will the server send back?
What is an API contd: API calls can take place in many places between software components ● Inside a single program ○ e.g. word processor editing module and spell checking library ● Between two programs on one computer ○ The fitness app on your smartwatch and the sensor firmware ● Across the network ○ e.g. between your phone and the Google Maps data servers
How are APIs used? ● Today most visible API use is across the network ○ Cloud servers doing stuff for: other cloud servers; on premise services; smart phones; desktop computers etc. ● But sometimes not. Consider the API on your smart watch ● Network API traffic is often across https (post, get,...) ○ Example of Specific API protocols build on top of https ■ ● RESTful, XML-RPC, gRPC, GraphQL... Pub/Sub for many to many asynchronous message exchange
So API Docs? Note - DITA information types are still relevant: ● Concept ● Topic ● Reference Mostly the same as product docs, but also a little different We start with the same questions: 1. 2. 3. 4. Who needs this and what are they trying to do? How can they achieve this? What information do they need? What is the most effective way to present this information? NOTE: The following notes assume a public web API with a wide audience.
Who? On a public API it can be ANYONE 1. Might not use the same written/spoken language as you 2. Have different objectives to the ones you imagined 3. Have a wide range of experience and knowledge 4. Use many different programming languages and libraries
What are they trying to achieve? Often something you cannot currently imagine! You think it's an accounting interface, someone else will have different ideas With a wide range of technologies So set the expectation on what is possible and what is sensible. Document clear boundaries
Content Themes Your Audience Needs Accurate, precise & current information Because APIs often follow a continuous deployment model outside your release schedule Understand what's achievable & the effective way to do it APIs are like a Lego set, not a doll's house Concepts and Scenarios -- the complete lifecycle(s) of Devs usually don't use your product and don't solutions understand it. They need context Working examples Developers will work faster starting with a working example Reference material -- API Specifications Programming needs precise, detailed and accurate information
Important Message One ● API Reference Docs alone are NOT GOOD ENOUGH ○ ● Just throwing Swagger or similar docs onto a website is not helpful! We also need ○ What, Why and How (Concept) ○ Getting started guides (Task) ○ Security information (Task and reference) ○ Complex use cases (Task) ○ Error recovery (Task and reference)
Important Message Two ● ● Demonstrate & Discuss complex use cases Document how things can go wrong and how to handle it You can't control the environments in which the integrations run. Assume Murphy's Quantum Law is in play: Anything that can, could have, or will go wrong, is going wrong, all at once. Paul Dickson, in The Official Rules (1982) ● Provide complete examples Simple examples will not help developers create real world solutions
Important Message Three Security in the Internet age is important API security is important! Make sure your API is secure DOCUMENT YOUR API SECURITY Shared secrets, username and password, JWT, TLS, ….
Effective Presentation & Content Suggestion Because Web pages or developer portal Easy to update, easy to access Complete code examples Development is a practical craft Lots of diagrams Make complex relationships & details clear "Proper" authoring tools are perhaps not best choice Fast turnaround API Docs sit near the code Help product teams to help you
Work with the product team Your API documentation is: 1. 2. Closely linked to the corresponding product code Contains a lot of technical content Keep the docs close to the code: 1. 2. Get the developers maintaining as much of the material as possible Follow the developer life cycle and make updates as easy as code change See also Docs as Code
Tools and formats ● Something you can use with your devs. ○ ● Your current doc tool may not be suitable... Plain text based helps more people contribute ○ e.g. Markdown or reStructuredText ● Code snippets from working code. Automatically include code changes ● Create diagrams from text ○ ● API reference generator tools. ○ ● E.g. Plantuml, Graphviz E.g. Swagger Automatic checking, formatting, generation & publication
Creating Diagrams from text @startuml collections Clients participant Server database Database Clients -> Server: Request and details Server --> Database: Query Server <-- Database: Data Server --> Server: Processing alt Success Clients <- Server: Status and information else Failure Clients <- Server: Error codes and information end @enduml PLANTUML
Further information Some places to start: https://apithedocs.org/ http://www.writethedocs.org/guide/api/about-api-documentation/ https://pronovix.com/blog/infographic-what-developer-portal More Advanced information: https://github.com/alecthegeek/doc-api-old-skool/wiki/Article https://www.openapis.org/about for RESTful APIs
More and more software companies today provide, not just software products, but Application Programming Interfaces (APIs) as well. They do this to encourage customers and partners to connect the software product to other software systems. As more and more software is moved to the cloud, these connections between systems become vital to the customers who want to use your product.
Documenting APIs is, in many ways, similar to creating product documentation. But there are also some important differences and this talk briefly discusses these issues for technical writers who have not documented APIs before.
Alec Clews provides an introduction to creating effective API documentation for technical writers who have only written product or user manuals.
Agenda
No prior technical knowledge is assumed, this talk is suitable for novices and anyone who has never documented an API before.
The following resources were mentioned during the presentation or are useful additional information.
You can find me online as alecthegeek
Pronovix are an developer portal specialist and have a range of resources
An article Alec wrote about what docs developers need and how he solved the "Docs as Code" problem
An example of some public API documentation. Excellent starting point onhow to structure your own API docs
RESTful APIs are the most common type of network API technology at the moment
XML-RPC is now legacy technology, but there are still a lot of systems that support it
A newer API technology
A newer API technology
Not strictly an API technology, but a scalable way for systems to pass messages to each other asynchronously in a many to many configuration
An example of some API reference docs created with the Swagger tool.
Creates UML and similar diagrams to include in your docs
Draws graphs (connected nodes) and similar diagrams
Conference series about API documentation and developer portals
It's little sparse....
for free. You
can too.