Ivana Isadora Devcic - From Zero to Spec-first API Hero

Ivana Isadora Devcic

Technical Writer and Documentation Specialist at ReversingLabs

Ivana's presentation(video recording)

Ivana's slides

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

Consequences:

• 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?

1. 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
   
   

2. 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
   
   

3. 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)
   
   

4. 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
   
   

5. Taking responsibility

   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
• Education completed
• New process discussed and accepted

Lessons learned

• 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