How can a technical writer make a difference and change broken API design processes? Why is it an obstacle if the API design process is not making use of API definitions?
Goal of the Design/Spec-first approach
To help to improve API design and documentation by supporting a better collaboration throughout the API lifecycle
Catch inconsistencies, usability issues, and get feedback early on to ensure use cases are satisfied
Unblock documentation tasks, allow teams to work simultaneously, and automate actions based on a shared, single source of truth
It is necessary for the techwriter to pursue this approach, and it is in their best interest, also.
Obstacles in the API design process
An uncoordinated design process might result in an API version that is totally different from the one planned and may challenge swagger improvements.
Problems can be related to:
Your company has no API definitions available to customers
The API design process doesn’t include writing API definitions
Developers can’t find docs for internal API
API documentation is written last-minute and includes a slow and ineffective review process
Unclear responsibility of API testing
API development goes back and forth because of unclear requirements.
If customers are asking for something you can’t deliver or development is not achieving goals on time, this cannot be just a documentation problem and needs to be dealt with on a higher level.
How to be the lead on the change?
Framing it as a business problem - which it actually is
a.) Make sure everyone is on the same page that this is a problem you should tackle all together
b.) Treat it as a proper project: assign responsibilities and metrics
c.) Plan and present how you want to implement spec-first API design aligned with business goals and roadmaps
d.) Try to get buy-ins from Management by comparing/presenting what the competition has
Being the teacher
a.) Educate, organize workshops, show how to use various tools
b.) Highlight benefits of version control - definitions can be treated just like code
Demonstrate automation with API definitions
a.) Introduce the idea of automated testing, show how to generate reference docs, provide advice for using linters
b.) Highlight reusability of API definitions, and that multiple teams can benefit from it (e.g., QA engineers, testing teams)
If experiencing resistance
a.) Understand reasons for resistance - don’t take it personally, receive it with empathy
b.) Acknowledge technical obstacles
c.) Ensure minimal workflow interruption - avoid creating an environment of us vs. them
d.) Be open to communication and conflict resolution
a.) Participate in API design sessions and observe pain points
b.) Lead data and real-world examples by attending conferences for inspiration, follow research and case studies
c.) Give people an opportunity to take part in the new process
d.) Be ready to compromise in a healthy way
Checklist: Are you ready?
Problem identified and agreed on
Plans and action items prepared
Tools tested and selected
New process discussed and accepted
Prioritize this project properly from the beginning, don’t treat it as a side project
All for One - It has to be a cross-team effort
No Third Parties - Communicate with the stakeholders directly
Beware of Bad Timing - Wait for the right moment to strike
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.