Write to retain new users. Optimize your docs for novice users via beginner-friendly tutorials. But how can writers look at content they already know anew? In her talk, Alaina sums up 7 guidelines with loads of tips to follow and includes practical examples taken from companies like Clarifai, Twilio and GitHub.
Offer a quick start
Perform a tech audit
Remember your environment
Share next steps
Stick to the standard library
Use inclusive language
Quality tutorials result in API user growth
Proofreading improves tutorial quality → quality tutorials lead to beginner retention → retention fosters a healthy community → community augments API user growth.
ABN AMRO recently launched their API developer portal Pronovix also worked on. We are all super proud of it!
Koen showed us what it takes in a large financial organization to get such an initiative supported and realized into a live platform, and how they see their future path as an aggregator of many sectors. Albeit his presentation is not to be published in its entirety, we got approval for this one slide.
Unclear documentation can lead to more adoption friction and often means that organizations with larger deployments face challenges with using your application at scale. At MongoDB, the API documentation was difficult to use. When trying to update that documentation, Anthony and colleagues discovered that how they managed those docs was unsustainable. In trying to help their users scale, they saw that they needed to help themselves scale the documentation:
Refactor the docs: what do we have and what do we need to change?
Refactor the process: do research before revising the process,
Plan more, execute less,
Establish own best practices to make the API specification consistent and complete,
Schedule the work: prioritize what to convert,
Automate the API specification and document how to use the API.
7 takeaways from MongoDB’s docs process
The API specification is not the API docs, only part of it,
Automate the API specification,
Work with your engineers on revising the API specification,
Set and stick to standards,
Test your API: use it to be able to explain it on multiple platforms,
Plan for incremental rollout,
Invest in tutorials: focus on tasks and activities.
Programmers often struggle writing API documentation that is free-form text based. There are several products on the market - like Hypermedia/Hateous, OpenAPI Initiative, and GraphQL - that allow for self-documented API references, but what exactly do they offer us? In his presentation, Roman provides us with several demos and examples, but also lists perks and insufficiencies.
Self-documented API documentation as a whole?
The references are only part of the API documentation. As a whole, API documentation could be categorized into:
Technical details (How to send a request and extract data from the response?) that can be self-documented,
Conceptual documentation (Why do we need this API?), which cannot be self-documented.
Conclusion: Establish API description formats as a middle ground (write concepts alongside code) and enable developers and tech writers to collaborate according to docs like code.
In-between self-documented and written documentation: takeaways
Reference docs are only part of the API documentation,
Developers can auto-generate some parts of the API documentation,
Technical writers are absolutely required to write the other parts,
Laurent demo-ed us how they use Swagger to generate a website for their APIs' documentation and specific clients for each language they support. Each time they update the spec they test it, update the website, build, test and deploy the new Clients libraries automatically. He showed us (live demo) how to set everything up from scratch thanks to Jenkins, Artifactory and Clever Cloud.
The production has to be perfect,
There is one process: build, then register, and live without data,
Keep the more updated version,
Statelessness is the key: create a factory of instances.
Inter-parameter constraints are common in web API specifications
In web API specifications, constraints come along with parameters. You need to satisfy every constraint for a request to succeed. API specification languages (API Blueprint, RAML, Swagger) and their tools help to ease that process, but do not yet provide a solution to express constraints across parameters (inter-parameter constraints).
Excellent presentation by Nathalie Oostvogels from @VUBrussel about how most APIs have inter-parameter constraints, and how none of the current API specification formats have good support for these. pic.twitter.com/mhfDQwr2dZ
Adyen’s rapid growth provides challenges concerning documentation. For their API references, they chose the Swagger tool (to implement the OpenAPI specification format - as Aleksei explains the semantic differences). The basic Swagger UI however, the speaker indicates, lacked an effective layout and provides problems with nested structures. How could Adyen go beyond?
Reimagining the Swagger UI: from specification to documentation
One user persona can wear different hats, and act e.g. as the learning developer or the coding developer,
Work in streams: have team members with different professional profiles,
Results: Among Adyen’s API Explorer’s first wins are support for multiple specs, adaptive layout, clean structure for nested objects, the multiple code examples.
Tips and tricks after building Adyen’s API Explorer
Let technical writers and developers collaborate on the same content,
DocOps: Engineering to help maintain the documentation
Adam talked about the open-source platform and tools they built when developing Nexmo Developer, for writing rich documentation collaboratively with ease. He talked about how they tackled problems concerning documentation requirements and met their goals.
How can people contribute on docs while keeping the quality high?
Think like an engineer: Build tools and processes that give the docs back to the contributing people (engineers, product owners, tech writers, customers, support, …).