Most of us are not going to change the world. Don’t let that stop you. You can still change the way APIs are created in your community, and reap the benefits of the spec-first design approach. Be the hero your community needs and your APIs deserve. Imagine a place where a lone technical writer is creating API specs by hand, from scratch, for a bunch of existing APIs. A place where developers don’t know if an API exists at all because there’s no documentation for it. Where product owners design new APIs in a single Excel spreadsheet. Places like that exist; maybe you’ve experienced something similar first-hand. Perhaps you thought to yourself, “I wish I could turn this place around”. And you can. You’re not “just a technical writer” - your perspective, insight, and skills are crucial for not just documenting, but also designing and developing usable APIs. In this talk, you will hear some ideas for what technical writers can do to make their job documenting APIs easier and collaboration with stakeholders stronger. We will look at the benefits of the spec-first approach, strategies for implementing it, and challenges you may encounter. A real-world example of building a spec-first API culture within a company will illustrate how long it took, what worked (and what didn’t), and where improvement is still needed. The goal is to equip technical writers with advice and motivation to start influencing API design decisions in their community. Documentarians represent the voice of the user to a great extent, but this voice is not always heard. Luckily, it’s not too late to change that.

1. From Zero
to Spec-First
API Hero
Ivana Isadora Devcic | API the Docs 2020

2. About me
Technical writer, translator,
FOSS advocate
Formerly: ReversingLabs
Currently: Redocly - we help
people make API docs they can
be proud of :)
Find me on Twitter:
@ivana_isadora
In this talk
Ideas and strategies for
increasing the adoption of
API definitions and improving
API design processes
No one-size-fits-all solutions
Disclaimers, disclaimers...

3. Our goal
Improve API
design & docs
by writing API
definitions first
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

5. API THE DOCS
START GAME

6. CEO:
HEY, I WANT THAT SWAGGER THING THE
COMPETITOR HAS. MAKE IT HAPPEN
FOR FREE.

7. CEO:
HEY, I WANT THAT SWAGGER THING THE
COMPETITOR HAS. MAKE IT HAPPEN
FOR FREE.
CUSTOMERS HAVE BEEN
REQUESTING OPENAPI
DEFINITIONS, BUT
WE DON'T HAVE ANY.

8. DEVELOPERS CAN'T FIND DOCS
FOR INTERNAL APIS.

9. DEVELOPERS CAN'T FIND DOCS
FOR INTERNAL APIS.
API DOCUMENTATION IS
WRITTEN LAST-MINUTE.
THE REVIEW PROCESS IS
SLOW AND INEFFECTIVE.

10. DEVELOPERS CAN'T FIND DOCS
FOR INTERNAL APIS.
API DEVELOPMENT GOES
BACK AND FORTH BECAUSE OF
UNCLEAR REQUIREMENTS.
MANAGEMENT IS UNHAPPY.
IS ANYONE EVEN TESTING ALL THESE
APIS? API DOCUMENTATION IS
WRITTEN LAST-MINUTE.
THE REVIEW PROCESS IS
SLOW AND INEFFECTIVE.

11. PLAYER ONE

12. EQUIP ITEM: POTION OF BUSINESS ACUMEN
Frame it as a business problem
Assign responsibilities
Agree on success metrics
Magic words: management buy-in,
cross-functional teams

13. EQUIP ITEM: HELMET OF INSIGHT
Educate, organize workshops
Show how to use various tools
Highlight benefits of version control
Magic words: expertise, trust, demystifying
perceived complexity

14. EQUIP ITEM: SCROLL OF AUTOMATION
Introduce the idea of automated testing
Show how to auto-generate reference docs
Provide advice for using linters
Magic words: consistency, reuse,
mutual benefits

15. EQUIP ITEM: SHIELD OF EMPATHY
Understand reasons for resistance
Acknowledge technical obstacles
Ensure minimal workflow interruption
Magic words: open communication,
conflict resolution, respect

16. EQUIP ITEM: SWORD OF LEADERSHIP
Participate in design sessions
Observe pain points
Lead with data and real-world examples
Magic words: responsibility, credibility,
inclusion

17. READY?
+ Problem identified and agreed on
+ Plans and action items prepared
+ Tools tested and selected
+ Education completed
+ New process discussed and accepted

18. 2019 Q2
Project kicked off. Started with research,
testing OpenAPI tools, and writing
definitions for existing APIs manually.
2020 Q1
Developers wrote definitions for two new
APIs, but after they had already been
developed (not during the design phase).
2020 Q2
Idea for technical writers to join API design
sessions floating around. Project put on
hold due to other priorities.
2019 Q4
First batch of API definitions written,
successful demo. Started getting
developers on board (individually).

19. You're the hero leading the charge,
but ultimately it must be a cross-
team collaborative effort.
Don't frame it as "us vs them".
If you agree it's a common problem,
everyone should work together
to solve it.
Communicate with the stakeholders
directly - don't let others relay
messages for you. They may leave
out important technical details.
Nuances can get lost, and no one
else can convey the passion you
have for the project.
There's no point in pushing if the
teams are not ready for the change
yet, overwhelmed with other work,
understaffed, or their priorities are
constantly shifting. Sometimes you
just have to wait for the right
moment to strike.
All for One No Third Parties Beware of Bad Timing
Lessons Learned
OUR PRINCESS IS IN ANOTHER CASTLE...

20. "HEROES ARE MADE IN THE HOUR OF DEFEAT.
SUCCESS IS, THEREFORE, WELL DESCRIBED AS
A SERIES OF GLORIOUS DEFEATS."
MAHATMA GANDHI
RESTART GAME?

21. IT'S DANGEROUS TO GO
ALONE! TAKE THESE.
writethedocs.org apithedocs.org

22. GAME OVER
Thanks for playing!
twitter.com/ivana_isadora
ivana@redoc.ly