Fabrizio Ferri-Benedetti - When documenting is designing: How to assist API design as a technical writer

This is a summary of a talk given at Write the Docs Prague 2021.

Fabrizio majored in psychology in university and lives in Barcelona. He's a senior staff technical writer at Splunk, and previously worked as a technical writer at other organizations. 

He says that tech writers can improve anything built with words. It can shape your career if you strongly believe in it. This can include UI text, tech docs, metadata, code and copy. Anything that is written can be improved by the writer. 

Words happen everywhere, especially in technical products. In the backend you might have code comments, APIs, UIs and workflows. 

Words also happen to be design. APIs and UIs both have writing. The words you use to describe your API enable conversations between software and people. Technical writers are very suited to help technical teams with API design. 

What makes APIs special? API designs are made of words. Responses such as error responses or success responses carry a message that is sent to users. Everywhere you look are words we can improve. 

Code is run and a response is sent back to the client, which is a conversation using words. 

Designing an API is about choosing the right words to enable systems to converse. API design allows systems to talk to each other in an effective way. It also depends on how you build APIs. 

API First or Code First

It can be API First or Code First. Documentation comes first in API First. Code First starts with the code, and documentation comes later. 

The problem with Code First APIs is that several teams may end up designing API conversations that are at odds with each other and may not match customer expectations. You end up with lots of inconsistencies. 

An API First workflow starts with a user story. You draft your API design and create initial docs between several teams who can coordinate together. 

API design is a shared responsibility, not just one person. It can be shared between an Engineering Manager, API architect, API technical writer, API Developers, and QA engineers.  

API designers and technical writers have lots of overlap, both using their primary tool of words to get the job done. 

Documenting a bad API takes more time and generates less satisfaction, and the end result is bad documentation. Since API design is a shared responsibility, but no one officially takes care of it, technical writers should step in and take some ownership. 

How can you get into API design? Start with a simple question: “How can I help?” He reached out to the API team and offered to support them. 

Fabrizio has some tips for assisting in API design as a technical writer. 

1. Advocate for API First

Pitch API First design internally, and find allies in engineering and product management. Draft API First workflows and procedures based on your tech stack, then pitch them or ask for feedback. You can still do API First AND generate API specs from the code. 

2. Push for API Design guidelines

Guidelines make things more likely to happen. Make it collaborative (it’s not about building something from your ivory tower), gather feedback and be open to changes. Create an API Design template based on the guidelines, which can be as simple as a word document.

3. Create an API style guide for docs

Design and docs guidelines partially overlap. Cover how contributors should write descriptions. Think about the terminology of your API/platform. 

4. Own summaries and descriptions

Documentation entities in API specification formats are technical writing strongholds, and you should own them. Embed yourself in the design process so that you can be the editor of all documentation fields. Make it easy for stakeholders to request reviews. Don’t go for an overly complicated workflow. 

5. Provide naming expertise

As a writer, you can provide naming expertise. Naming is a key aspect of API design, since resources and parameters are also resources that require careful naming decisions. Start by suggesting alternatives and/or raising concerns. Naming issues can be a symptom of something bigger, such as product decisions or terminology issues in the industry. 

6. Join or set up API design reviews

API design reviews are for approving design decisions, and getting everyone in the same room/chat is the key goal. Keep the rules simple and always set an agenda. 

7. Fight for meaningful error messages

These are often overlooked but API consumers see tons of errors every day. Error codes should make sense semantically, and be clear and useful. Tech writers are often the first API consumers, so as soon as you see them make sure you get your feedback to the right place. 

8. Build an internal API viewer

Internal API viewers are the town squares of API design. Build a simple solution to load in progress API specs, which can be a prelude to the client-facing dev portal. 

Final remarks

Overall, follow Fabrizio’s tips for implementing API First design in your organization. Technical writers can improve anything to do with words, and there are lots of opportunities to do this within APIs. Put yourself forward and offer your expertise to the developers. 

Listen to the full talk here.