When documenting is designing: How to assist API design as a technical writer¶
Sketchnote
Description
The programmatic equivalent of UX Writing is API Design. The words that you use to describe your API enable conversations between software and people - it's just a bit more structured and mechanical. That's why technical writers are uniquely suited to assist technical teams in doing API design, especially when an API First design approach is being followed.
When documenting a web API, technical writers may end up identifying areas of improvement in the way it's designed. Much like it happens with user documentation for user interfaces, there's a big opportunity for making your voice be heard upstream, where APIs are designed and implemented. It takes time, and the right processes, but the end result is better documentation, too.
In this talk I'll tell you how I began my API design journey at Ohpen and the kind of processes we put in place to align API design across teams, including an API design style guide that covered error messages, content reuse, and naming conventions, among other things. Along the way, I'll present some of the most common obstacles I faced and how I got around them.
- Conference: Write the Docs Prague
- Year: 2021
