This talk was presented at API The Docs Virtual 2022 event series on 9 November. We are glad to present the video recording, slide deck and talk summary below. Enjoy!
How do you present information that doesn't have a standardized documentation structure yet?
How do you follow up? What do you measure? How do you get feedback that you are on the right track?
How does the “Show, don’t tell” approach play together with accessibility rules and regulations of the law?
What are the things that you don’t find solvable yet, but that you’d love to see implemented?
In the case of web APIs, a plethora of frameworks and tools are available that can help you write, test, and render the API specifications. But how can you build documentation around non-REST APIs? How to structure such content? How to design it in a better way? Technical writers face such problems and dilemmas daily, but designers and developers are also involved in the issue.
Creating useful documentation is hard, because it should provide all the necessary information, and it also has to be:
easy-to-read,
findable,
helpful,
concise, and
prepared for returning users.
Creating useful documentation for Frontend SDKs or UI features is even harder. Especially, if you have to offer version-controlled and searchable docs for multiple such SDKs, based on different frameworks, under rapid, uncoordinated development with enhancements and breaking changes.
How to tackle the challenges
Information architecture and good writing are equally important.
Create an intro page that can help users navigate to the section they are interested in the most.
Don’t make your readers choose or guess where to start or what to do next. Use clear design.
A table of contents at the beginning of the sections can help the returning users continue their journey seamlessly.
Create a consistent documentation structure and page layout even if you have to document different platforms or frameworks: lower the context-switching cost for your readers.
Clearly explain everything, and highlight the possible differences.
Try to keep using the same flow and explanation steps or as similar as possible.
Always provide the necessary context. Complete information helps developers make better decisions.
Provide contextual environment- and platform-specific information as well.
Keep all relevant information in the same place.
Publish the reference pages separately.
Write proper references for all parameters.
Use a left- and right-side navigation where users can easily find all relevant options on the site and within the page.
Clearly differentiate all available options, and provide suitable code samples.
Use callouts, color notifications to draw attention to important points.
Write a glossary.
Publish a changelog.
Show, don’t tell. Design for developers!
What you can certainly do
Think of the user.
Think about what matters to them.
Try not to overwhelm them, but keep all necessary information accessible.
Help them understand interoperability between frameworks.
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.
