SlideShare une entreprise Scribd logo
1  sur  22
Télécharger pour lire hors ligne
From Zero
to Spec-First
API Hero
Ivana Isadora Devcic | API the Docs 2020
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...
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
From Zero to Spec-first API Hero
API THE DOCS
START GAME
CEO:
HEY, I WANT THAT SWAGGER THING THE
COMPETITOR HAS. MAKE IT HAPPEN
FOR FREE.
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.
DEVELOPERS CAN'T FIND DOCS
FOR INTERNAL APIS.
DEVELOPERS CAN'T FIND DOCS
FOR INTERNAL APIS.
API DOCUMENTATION IS
WRITTEN LAST-MINUTE.
THE REVIEW PROCESS IS
SLOW AND INEFFECTIVE.
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.
PLAYER ONE
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
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
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
EQUIP ITEM: SHIELD OF EMPATHY
Understand reasons for resistance
Acknowledge technical obstacles
Ensure minimal workflow interruption
Magic words: open communication,
conflict resolution, respect
EQUIP ITEM: SWORD OF LEADERSHIP
Participate in design sessions
Observe pain points
Lead with data and real-world examples
Magic words: responsibility, credibility,
inclusion
READY?
+ Problem identified and agreed on
+ Plans and action items prepared
+ Tools tested and selected
+ Education completed
+ New process discussed and accepted
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).
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...
"HEROES ARE MADE IN THE HOUR OF DEFEAT.
SUCCESS IS, THEREFORE, WELL DESCRIBED AS
A SERIES OF GLORIOUS DEFEATS."
MAHATMA GANDHI
RESTART GAME?
IT'S DANGEROUS TO GO
ALONE! TAKE THESE.
writethedocs.org apithedocs.org
GAME OVER
Thanks for playing!
twitter.com/ivana_isadora
ivana@redoc.ly

Contenu connexe

Tendances

User Testing in the Invisible World of APIs
User Testing in the Invisible World of APIsUser Testing in the Invisible World of APIs
User Testing in the Invisible World of APIsPronovix
 
Write what counts. Count What Counts.
Write what counts. Count What Counts.Write what counts. Count What Counts.
Write what counts. Count What Counts.Pronovix
 
Devportal Information Architecture: A 4-step Method
Devportal Information Architecture: A 4-step MethodDevportal Information Architecture: A 4-step Method
Devportal Information Architecture: A 4-step MethodPronovix
 
Building API Products
Building API ProductsBuilding API Products
Building API ProductsJames Samuel
 
Voxxed days 2015-hakansaglam-codereview
Voxxed days 2015-hakansaglam-codereviewVoxxed days 2015-hakansaglam-codereview
Voxxed days 2015-hakansaglam-codereviewHakan Saglam
 
apidays LIVE Singapore - Your API documentation powered by AI by Hervé Vu Rou...
apidays LIVE Singapore - Your API documentation powered by AI by Hervé Vu Rou...apidays LIVE Singapore - Your API documentation powered by AI by Hervé Vu Rou...
apidays LIVE Singapore - Your API documentation powered by AI by Hervé Vu Rou...apidays
 
Engineer Stunning (API) documentation
Engineer Stunning (API) documentationEngineer Stunning (API) documentation
Engineer Stunning (API) documentationPronovix
 
Mistakes to-avoid-api-product
Mistakes to-avoid-api-productMistakes to-avoid-api-product
Mistakes to-avoid-api-productRahul Dighe
 
Best mobile Apps Development Company in Bangladesh
Best mobile Apps Development Company in Bangladesh Best mobile Apps Development Company in Bangladesh
Best mobile Apps Development Company in Bangladesh XactIdea Limited
 
Developer Relations 101
Developer Relations 101Developer Relations 101
Developer Relations 101Felipe Pedroso
 
apidays LIVE Hong Kong - Why you need a DevRel team for your API by Anna Tsol...
apidays LIVE Hong Kong - Why you need a DevRel team for your API by Anna Tsol...apidays LIVE Hong Kong - Why you need a DevRel team for your API by Anna Tsol...
apidays LIVE Hong Kong - Why you need a DevRel team for your API by Anna Tsol...apidays
 
apidays LIVE Paris 2021 - Generating OpenAPIs from business models by Frederi...
apidays LIVE Paris 2021 - Generating OpenAPIs from business models by Frederi...apidays LIVE Paris 2021 - Generating OpenAPIs from business models by Frederi...
apidays LIVE Paris 2021 - Generating OpenAPIs from business models by Frederi...apidays
 
apidays LIVE London 2021 - Human-centred API Governance by Arnaud Lauret, Nat...
apidays LIVE London 2021 - Human-centred API Governance by Arnaud Lauret, Nat...apidays LIVE London 2021 - Human-centred API Governance by Arnaud Lauret, Nat...
apidays LIVE London 2021 - Human-centred API Governance by Arnaud Lauret, Nat...apidays
 
IoT App Development Company India, Hire IoT Developers
IoT App Development Company India, Hire IoT DevelopersIoT App Development Company India, Hire IoT Developers
IoT App Development Company India, Hire IoT DevelopersIndianAppDevelopers
 
INTERFACE, by apidays - APIs from consumption to contribution by Kristof Van...
INTERFACE, by apidays  - APIs from consumption to contribution by Kristof Van...INTERFACE, by apidays  - APIs from consumption to contribution by Kristof Van...
INTERFACE, by apidays - APIs from consumption to contribution by Kristof Van...apidays
 
Rebooting APIs at scale
Rebooting APIs at scaleRebooting APIs at scale
Rebooting APIs at scaleRahul Dighe
 
API Design Patterns: a guide to better APIs
API Design Patterns: a guide to better APIsAPI Design Patterns: a guide to better APIs
API Design Patterns: a guide to better APIsManning Publications
 
apidays LIVE India - The link between technical documentation and developer e...
apidays LIVE India - The link between technical documentation and developer e...apidays LIVE India - The link between technical documentation and developer e...
apidays LIVE India - The link between technical documentation and developer e...apidays
 

Tendances (20)

User Testing in the Invisible World of APIs
User Testing in the Invisible World of APIsUser Testing in the Invisible World of APIs
User Testing in the Invisible World of APIs
 
Write what counts. Count What Counts.
Write what counts. Count What Counts.Write what counts. Count What Counts.
Write what counts. Count What Counts.
 
Devportal Information Architecture: A 4-step Method
Devportal Information Architecture: A 4-step MethodDevportal Information Architecture: A 4-step Method
Devportal Information Architecture: A 4-step Method
 
Building API Products
Building API ProductsBuilding API Products
Building API Products
 
Voxxed days 2015-hakansaglam-codereview
Voxxed days 2015-hakansaglam-codereviewVoxxed days 2015-hakansaglam-codereview
Voxxed days 2015-hakansaglam-codereview
 
apidays LIVE Singapore - Your API documentation powered by AI by Hervé Vu Rou...
apidays LIVE Singapore - Your API documentation powered by AI by Hervé Vu Rou...apidays LIVE Singapore - Your API documentation powered by AI by Hervé Vu Rou...
apidays LIVE Singapore - Your API documentation powered by AI by Hervé Vu Rou...
 
Engineer Stunning (API) documentation
Engineer Stunning (API) documentationEngineer Stunning (API) documentation
Engineer Stunning (API) documentation
 
Mistakes to-avoid-api-product
Mistakes to-avoid-api-productMistakes to-avoid-api-product
Mistakes to-avoid-api-product
 
Best mobile Apps Development Company in Bangladesh
Best mobile Apps Development Company in Bangladesh Best mobile Apps Development Company in Bangladesh
Best mobile Apps Development Company in Bangladesh
 
Developer Relations 101
Developer Relations 101Developer Relations 101
Developer Relations 101
 
apidays LIVE Hong Kong - Why you need a DevRel team for your API by Anna Tsol...
apidays LIVE Hong Kong - Why you need a DevRel team for your API by Anna Tsol...apidays LIVE Hong Kong - Why you need a DevRel team for your API by Anna Tsol...
apidays LIVE Hong Kong - Why you need a DevRel team for your API by Anna Tsol...
 
apidays LIVE Paris 2021 - Generating OpenAPIs from business models by Frederi...
apidays LIVE Paris 2021 - Generating OpenAPIs from business models by Frederi...apidays LIVE Paris 2021 - Generating OpenAPIs from business models by Frederi...
apidays LIVE Paris 2021 - Generating OpenAPIs from business models by Frederi...
 
apidays LIVE London 2021 - Human-centred API Governance by Arnaud Lauret, Nat...
apidays LIVE London 2021 - Human-centred API Governance by Arnaud Lauret, Nat...apidays LIVE London 2021 - Human-centred API Governance by Arnaud Lauret, Nat...
apidays LIVE London 2021 - Human-centred API Governance by Arnaud Lauret, Nat...
 
IoT App Development Company India, Hire IoT Developers
IoT App Development Company India, Hire IoT DevelopersIoT App Development Company India, Hire IoT Developers
IoT App Development Company India, Hire IoT Developers
 
INTERFACE, by apidays - APIs from consumption to contribution by Kristof Van...
INTERFACE, by apidays  - APIs from consumption to contribution by Kristof Van...INTERFACE, by apidays  - APIs from consumption to contribution by Kristof Van...
INTERFACE, by apidays - APIs from consumption to contribution by Kristof Van...
 
Rebooting APIs at scale
Rebooting APIs at scaleRebooting APIs at scale
Rebooting APIs at scale
 
API Design Patterns: a guide to better APIs
API Design Patterns: a guide to better APIsAPI Design Patterns: a guide to better APIs
API Design Patterns: a guide to better APIs
 
Swiggy JD
Swiggy JDSwiggy JD
Swiggy JD
 
apidays LIVE India - The link between technical documentation and developer e...
apidays LIVE India - The link between technical documentation and developer e...apidays LIVE India - The link between technical documentation and developer e...
apidays LIVE India - The link between technical documentation and developer e...
 
Resume Suraj
Resume SurajResume Suraj
Resume Suraj
 

Similaire à From Zero to Spec-first API Hero

Lean Startup Machine - Mobile App Development
Lean Startup Machine - Mobile App DevelopmentLean Startup Machine - Mobile App Development
Lean Startup Machine - Mobile App DevelopmentAravind Krishnaswamy
 
Strange but True: Counterintiutive Paths to Building a Business on APIs
Strange but True: Counterintiutive Paths to Building a Business on APIsStrange but True: Counterintiutive Paths to Building a Business on APIs
Strange but True: Counterintiutive Paths to Building a Business on APIsThomas Bouldin
 
Are you a lean mobile startup? Applying lean startup principles to mobile app...
Are you a lean mobile startup? Applying lean startup principles to mobile app...Are you a lean mobile startup? Applying lean startup principles to mobile app...
Are you a lean mobile startup? Applying lean startup principles to mobile app...Aravind Krishnaswamy
 
Developers Nepal Meetup #4 Report
Developers Nepal Meetup #4 ReportDevelopers Nepal Meetup #4 Report
Developers Nepal Meetup #4 ReportPunit Jajodia
 
Top 10 Lessons Learned - In our ongoing shift from portal to platform
Top 10 Lessons Learned - In our ongoing shift from portal to platformTop 10 Lessons Learned - In our ongoing shift from portal to platform
Top 10 Lessons Learned - In our ongoing shift from portal to platformDavid Haskiya
 
Applying a Developer-Centric Approach to API Design from API Architect Ronnie...
Applying a Developer-Centric Approach to API Design from API Architect Ronnie...Applying a Developer-Centric Approach to API Design from API Architect Ronnie...
Applying a Developer-Centric Approach to API Design from API Architect Ronnie...CA API Management
 
If you Build APIs will Developers Come?
If you Build APIs will Developers Come?If you Build APIs will Developers Come?
If you Build APIs will Developers Come?Apigee | Google Cloud
 
Computer Science Internship Report PDF Leena AI
Computer Science Internship Report PDF Leena AIComputer Science Internship Report PDF Leena AI
Computer Science Internship Report PDF Leena AIshadowhazard77
 
User Centered Design: guarantee that your business process automation project...
User Centered Design: guarantee that your business process automation project...User Centered Design: guarantee that your business process automation project...
User Centered Design: guarantee that your business process automation project...Bonitasoft
 
Computer Science Internship Report Leena AI
Computer Science Internship Report Leena AIComputer Science Internship Report Leena AI
Computer Science Internship Report Leena AIshadowhazard77
 
From API-First to SDK-First
From API-First to SDK-FirstFrom API-First to SDK-First
From API-First to SDK-FirstNordic APIs
 
APIs as a Product Strategy
APIs as a Product StrategyAPIs as a Product Strategy
APIs as a Product StrategyRavi Kumar
 
[DevRelCon Earth 2020] Developers, be the evangelist
[DevRelCon Earth 2020] Developers, be the evangelist[DevRelCon Earth 2020] Developers, be the evangelist
[DevRelCon Earth 2020] Developers, be the evangelistWoohyeok Kim
 
API first.pptx
API first.pptxAPI first.pptx
API first.pptxOdedApel
 
apidays Australia 2022 - API design challenges and making APIs your common la...
apidays Australia 2022 - API design challenges and making APIs your common la...apidays Australia 2022 - API design challenges and making APIs your common la...
apidays Australia 2022 - API design challenges and making APIs your common la...apidays
 
Software Craftsmanship - JAX London 2011
Software Craftsmanship - JAX London 2011Software Craftsmanship - JAX London 2011
Software Craftsmanship - JAX London 2011Sandro Mancuso
 
EIA2019Italy - Design Thinking & Paper Prototyping - Ali El Amrani
EIA2019Italy - Design Thinking & Paper Prototyping - Ali El AmraniEIA2019Italy - Design Thinking & Paper Prototyping - Ali El Amrani
EIA2019Italy - Design Thinking & Paper Prototyping - Ali El AmraniEuropean Innovation Academy
 
API Product Management - Driving Success through the Value Chain
API Product Management - Driving Success through the Value ChainAPI Product Management - Driving Success through the Value Chain
API Product Management - Driving Success through the Value ChainApigee | Google Cloud
 

Similaire à From Zero to Spec-first API Hero (20)

Boss, we need an API!
Boss, we need an API!Boss, we need an API!
Boss, we need an API!
 
Lean Startup Machine - Mobile App Development
Lean Startup Machine - Mobile App DevelopmentLean Startup Machine - Mobile App Development
Lean Startup Machine - Mobile App Development
 
Strange but True: Counterintiutive Paths to Building a Business on APIs
Strange but True: Counterintiutive Paths to Building a Business on APIsStrange but True: Counterintiutive Paths to Building a Business on APIs
Strange but True: Counterintiutive Paths to Building a Business on APIs
 
Are you a lean mobile startup? Applying lean startup principles to mobile app...
Are you a lean mobile startup? Applying lean startup principles to mobile app...Are you a lean mobile startup? Applying lean startup principles to mobile app...
Are you a lean mobile startup? Applying lean startup principles to mobile app...
 
Developers Nepal Meetup #4 Report
Developers Nepal Meetup #4 ReportDevelopers Nepal Meetup #4 Report
Developers Nepal Meetup #4 Report
 
Top 10 Lessons Learned - In our ongoing shift from portal to platform
Top 10 Lessons Learned - In our ongoing shift from portal to platformTop 10 Lessons Learned - In our ongoing shift from portal to platform
Top 10 Lessons Learned - In our ongoing shift from portal to platform
 
Applying a Developer-Centric Approach to API Design from API Architect Ronnie...
Applying a Developer-Centric Approach to API Design from API Architect Ronnie...Applying a Developer-Centric Approach to API Design from API Architect Ronnie...
Applying a Developer-Centric Approach to API Design from API Architect Ronnie...
 
If you Build APIs will Developers Come?
If you Build APIs will Developers Come?If you Build APIs will Developers Come?
If you Build APIs will Developers Come?
 
Computer Science Internship Report PDF Leena AI
Computer Science Internship Report PDF Leena AIComputer Science Internship Report PDF Leena AI
Computer Science Internship Report PDF Leena AI
 
User Centered Design: guarantee that your business process automation project...
User Centered Design: guarantee that your business process automation project...User Centered Design: guarantee that your business process automation project...
User Centered Design: guarantee that your business process automation project...
 
Computer Science Internship Report Leena AI
Computer Science Internship Report Leena AIComputer Science Internship Report Leena AI
Computer Science Internship Report Leena AI
 
From API-First to SDK-First
From API-First to SDK-FirstFrom API-First to SDK-First
From API-First to SDK-First
 
APIs as a Product Strategy
APIs as a Product StrategyAPIs as a Product Strategy
APIs as a Product Strategy
 
[DevRelCon Earth 2020] Developers, be the evangelist
[DevRelCon Earth 2020] Developers, be the evangelist[DevRelCon Earth 2020] Developers, be the evangelist
[DevRelCon Earth 2020] Developers, be the evangelist
 
API first.pptx
API first.pptxAPI first.pptx
API first.pptx
 
apidays Australia 2022 - API design challenges and making APIs your common la...
apidays Australia 2022 - API design challenges and making APIs your common la...apidays Australia 2022 - API design challenges and making APIs your common la...
apidays Australia 2022 - API design challenges and making APIs your common la...
 
Software Craftsmanship - JAX London 2011
Software Craftsmanship - JAX London 2011Software Craftsmanship - JAX London 2011
Software Craftsmanship - JAX London 2011
 
EIA2019Italy - Design Thinking & Paper Prototyping - Ali El Amrani
EIA2019Italy - Design Thinking & Paper Prototyping - Ali El AmraniEIA2019Italy - Design Thinking & Paper Prototyping - Ali El Amrani
EIA2019Italy - Design Thinking & Paper Prototyping - Ali El Amrani
 
Developing for Developers
Developing for DevelopersDeveloping for Developers
Developing for Developers
 
API Product Management - Driving Success through the Value Chain
API Product Management - Driving Success through the Value ChainAPI Product Management - Driving Success through the Value Chain
API Product Management - Driving Success through the Value Chain
 

Plus de Pronovix

By the time they're reading the docs, it's already too late
By the time they're reading the docs, it's already too lateBy the time they're reading the docs, it's already too late
By the time they're reading the docs, it's already too latePronovix
 
Optimizing Dev Portals with Analytics and Feedback
Optimizing Dev Portals with Analytics and FeedbackOptimizing Dev Portals with Analytics and Feedback
Optimizing Dev Portals with Analytics and FeedbackPronovix
 
Success metrics when launching your first developer portal
Success metrics when launching your first developer portalSuccess metrics when launching your first developer portal
Success metrics when launching your first developer portalPronovix
 
Documentation, APIs & AI
Documentation, APIs & AIDocumentation, APIs & AI
Documentation, APIs & AIPronovix
 
Making sense of analytics for documentation pages
Making sense of analytics for documentation pagesMaking sense of analytics for documentation pages
Making sense of analytics for documentation pagesPronovix
 
Feedback cycles and their role in improving overall developer experiences
Feedback cycles and their role in improving overall developer experiencesFeedback cycles and their role in improving overall developer experiences
Feedback cycles and their role in improving overall developer experiencesPronovix
 
GraphQL Isn't An Excuse To Stop Writing Docs
GraphQL Isn't An Excuse To Stop Writing DocsGraphQL Isn't An Excuse To Stop Writing Docs
GraphQL Isn't An Excuse To Stop Writing DocsPronovix
 
API Documentation For Web3
API Documentation For Web3API Documentation For Web3
API Documentation For Web3Pronovix
 
Why your API doesn’t solve my problem: A use case-driven API design
Why your API doesn’t solve my problem: A use case-driven API designWhy your API doesn’t solve my problem: A use case-driven API design
Why your API doesn’t solve my problem: A use case-driven API designPronovix
 
unREST among the docs
unREST among the docsunREST among the docs
unREST among the docsPronovix
 
Developing a best-in-class deprecation policy for your APIs
Developing a best-in-class deprecation policy for your APIsDeveloping a best-in-class deprecation policy for your APIs
Developing a best-in-class deprecation policy for your APIsPronovix
 
Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone
Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyoneAnnotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone
Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyonePronovix
 
What do developers do when it comes to understanding and using APIs?
What do developers do when it comes to understanding and using APIs?What do developers do when it comes to understanding and using APIs?
What do developers do when it comes to understanding and using APIs?Pronovix
 
Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Inclusive, Accessible Tech: Bias-Free Language in Code and ConfigurationsInclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Inclusive, Accessible Tech: Bias-Free Language in Code and ConfigurationsPronovix
 
Creating API documentation for international communities
Creating API documentation for international communitiesCreating API documentation for international communities
Creating API documentation for international communitiesPronovix
 
One Developer Portal to Document Them All
One Developer Portal to Document Them AllOne Developer Portal to Document Them All
One Developer Portal to Document Them AllPronovix
 
Docs-as-Code: Evolving the API Documentation Experience
Docs-as-Code: Evolving the API Documentation ExperienceDocs-as-Code: Evolving the API Documentation Experience
Docs-as-Code: Evolving the API Documentation ExperiencePronovix
 
Developer journey - make it easy for devs to love your product
Developer journey - make it easy for devs to love your productDeveloper journey - make it easy for devs to love your product
Developer journey - make it easy for devs to love your productPronovix
 
Complexity is not complicatedness
Complexity is not complicatednessComplexity is not complicatedness
Complexity is not complicatednessPronovix
 
How cognitive biases and ranking can foster an ineffective architecture and d...
How cognitive biases and ranking can foster an ineffective architecture and d...How cognitive biases and ranking can foster an ineffective architecture and d...
How cognitive biases and ranking can foster an ineffective architecture and d...Pronovix
 

Plus de Pronovix (20)

By the time they're reading the docs, it's already too late
By the time they're reading the docs, it's already too lateBy the time they're reading the docs, it's already too late
By the time they're reading the docs, it's already too late
 
Optimizing Dev Portals with Analytics and Feedback
Optimizing Dev Portals with Analytics and FeedbackOptimizing Dev Portals with Analytics and Feedback
Optimizing Dev Portals with Analytics and Feedback
 
Success metrics when launching your first developer portal
Success metrics when launching your first developer portalSuccess metrics when launching your first developer portal
Success metrics when launching your first developer portal
 
Documentation, APIs & AI
Documentation, APIs & AIDocumentation, APIs & AI
Documentation, APIs & AI
 
Making sense of analytics for documentation pages
Making sense of analytics for documentation pagesMaking sense of analytics for documentation pages
Making sense of analytics for documentation pages
 
Feedback cycles and their role in improving overall developer experiences
Feedback cycles and their role in improving overall developer experiencesFeedback cycles and their role in improving overall developer experiences
Feedback cycles and their role in improving overall developer experiences
 
GraphQL Isn't An Excuse To Stop Writing Docs
GraphQL Isn't An Excuse To Stop Writing DocsGraphQL Isn't An Excuse To Stop Writing Docs
GraphQL Isn't An Excuse To Stop Writing Docs
 
API Documentation For Web3
API Documentation For Web3API Documentation For Web3
API Documentation For Web3
 
Why your API doesn’t solve my problem: A use case-driven API design
Why your API doesn’t solve my problem: A use case-driven API designWhy your API doesn’t solve my problem: A use case-driven API design
Why your API doesn’t solve my problem: A use case-driven API design
 
unREST among the docs
unREST among the docsunREST among the docs
unREST among the docs
 
Developing a best-in-class deprecation policy for your APIs
Developing a best-in-class deprecation policy for your APIsDeveloping a best-in-class deprecation policy for your APIs
Developing a best-in-class deprecation policy for your APIs
 
Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone
Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyoneAnnotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone
Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone
 
What do developers do when it comes to understanding and using APIs?
What do developers do when it comes to understanding and using APIs?What do developers do when it comes to understanding and using APIs?
What do developers do when it comes to understanding and using APIs?
 
Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Inclusive, Accessible Tech: Bias-Free Language in Code and ConfigurationsInclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
 
Creating API documentation for international communities
Creating API documentation for international communitiesCreating API documentation for international communities
Creating API documentation for international communities
 
One Developer Portal to Document Them All
One Developer Portal to Document Them AllOne Developer Portal to Document Them All
One Developer Portal to Document Them All
 
Docs-as-Code: Evolving the API Documentation Experience
Docs-as-Code: Evolving the API Documentation ExperienceDocs-as-Code: Evolving the API Documentation Experience
Docs-as-Code: Evolving the API Documentation Experience
 
Developer journey - make it easy for devs to love your product
Developer journey - make it easy for devs to love your productDeveloper journey - make it easy for devs to love your product
Developer journey - make it easy for devs to love your product
 
Complexity is not complicatedness
Complexity is not complicatednessComplexity is not complicatedness
Complexity is not complicatedness
 
How cognitive biases and ranking can foster an ineffective architecture and d...
How cognitive biases and ranking can foster an ineffective architecture and d...How cognitive biases and ranking can foster an ineffective architecture and d...
How cognitive biases and ranking can foster an ineffective architecture and d...
 

Dernier

Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve DecarbonizationUsing IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve DecarbonizationIES VE
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfJamie (Taka) Wang
 
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...DianaGray10
 
Cybersecurity Workshop #1.pptx
Cybersecurity Workshop #1.pptxCybersecurity Workshop #1.pptx
Cybersecurity Workshop #1.pptxGDSC PJATK
 
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPAAnypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPAshyamraj55
 
Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024SkyPlanner
 
NIST Cybersecurity Framework (CSF) 2.0 Workshop
NIST Cybersecurity Framework (CSF) 2.0 WorkshopNIST Cybersecurity Framework (CSF) 2.0 Workshop
NIST Cybersecurity Framework (CSF) 2.0 WorkshopBachir Benyammi
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024D Cloud Solutions
 
Linked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond OntologiesLinked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond OntologiesDavid Newbury
 
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfIaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfDaniel Santiago Silva Capera
 
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Will Schroeder
 
VoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXVoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXTarek Kalaji
 
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfUiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfDianaGray10
 
Building AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptxBuilding AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptxUdaiappa Ramachandran
 
Designing A Time bound resource download URL
Designing A Time bound resource download URLDesigning A Time bound resource download URL
Designing A Time bound resource download URLRuncy Oommen
 
UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6DianaGray10
 
UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7DianaGray10
 
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCost
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCostKubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCost
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCostMatt Ray
 
Machine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfMachine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfAijun Zhang
 

Dernier (20)

Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve DecarbonizationUsing IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
 
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
 
Cybersecurity Workshop #1.pptx
Cybersecurity Workshop #1.pptxCybersecurity Workshop #1.pptx
Cybersecurity Workshop #1.pptx
 
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPAAnypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPA
 
Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024
 
NIST Cybersecurity Framework (CSF) 2.0 Workshop
NIST Cybersecurity Framework (CSF) 2.0 WorkshopNIST Cybersecurity Framework (CSF) 2.0 Workshop
NIST Cybersecurity Framework (CSF) 2.0 Workshop
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024
 
Linked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond OntologiesLinked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond Ontologies
 
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfIaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
 
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
 
VoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXVoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBX
 
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfUiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
 
Building AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptxBuilding AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptx
 
Designing A Time bound resource download URL
Designing A Time bound resource download URLDesigning A Time bound resource download URL
Designing A Time bound resource download URL
 
UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6
 
UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7
 
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCost
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCostKubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCost
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCost
 
Machine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfMachine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdf
 
20150722 - AGV
20150722 - AGV20150722 - AGV
20150722 - AGV
 

From Zero to Spec-first API Hero

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