SlideShare a Scribd company logo
1 of 25
Download to read offline
Doc Well for DevRel
API Days Interface
June 2020
Ilona Koren-Deutsch
Technical Documentation Manager, Twitch
About me
● None of my degrees are in anything to do with
software.
● I’ve been a technical writer for about 25 years, not
counting detours as a support engineer, curriculum
developer, and chef (garde manger then chef de
cuisine).
● I am a strong believer in the value of taking sabbaticals.
About my job
● I’m on the Developer Relations team.
● In the past I have mostly been part of engineering
teams, once curriculum development, and once
support.
● There are clear differences.
A different view
Pros
● Firsthand knowledge of
product (and
changes/deadlines)
● JIRA
● Close relationship with
developers and dev
managers
Tech writing in Engineering
Cons
● No big-picture view of
doc UX
● No customer contact
● Tendency towards silos
Pros
● Customer contact
● See documentation in
use by own team
● Whole product view
● KB/articles
Tech writing in Support
Cons
● Unhappy-customer
contact
● Lack of access to
product before release
Tech writing in Developer Relations
Pros
● Direct access to
customers
● Beta testing
● Varied content
● Building the doc
experience
Cons
● Customers have direct
access to me
● “Business brain”
Building the doc experience
● All the information that documents the API:
○ Getting started or onboarding pages
○ References
○ SDKs
○ Guides
○ FAQs
○ Tutorials
Documentation
What makes good developer
documentation?
● Good organization
● Clear explanations
● Examples
● Consistency
● Interactive way to try API calls
● Comments section
● Support resources
What makes a good portal?
● How well it helps users understand the API
● How it establishes trust
● The ways in which it helps developers quickly start
using the API
● The quality of the API reference
● What forms of support it offers
Understand the API
● Consider the audience
○ Developer looking to get started: the newcomer
○ Developer debugging a specific issue in an existing client: the
debugger
○ CTO evaluating competing APIs: the decision maker
○ Product manager figuring out if X is possible with the API: the
searcher
● Include use cases and success stories
Establish trust
● Intuitive site architecture
● Navigation and search
● Changelog
● API monitor or dashboard
● Roadmap for upcoming features
● Terms of use
Accelerate “Time to Hello World”
● Registration process
● Developer onboarding:
○ Getting started guide
○ Tutorials
○ Videos
○ Code samples
API reference
● Authentication
● Status codes
● Error handling
● Sample code
● Example requests and responses
Provide support
● Support from the company:
○ Contact form
○ Twitter
○ Public NDA Slack
● Community support:
○ Forums
○ Meetups
Some thoughts on DX
Dev Portal
©
Peter Greenbaum
https://www.programmableweb.com/news/web-api-documentation-best-practices/2010/08/12
Keep adding content
● Documentation updates
● Blog posts
● Videos
● Event postings
Content-driven
● Design should underline your message
● Reduce frustration
● Do your user research
Navigation
● Navigation always visible
○ Top navigation
○ Fixed sticky navigation
○ Sidebar navigation, either fixed or openable/closable
● Page titles and breadcrumbs
● Provide suggestions of where to go next
○ Related content
○ Previous/next buttons
● Search available on every page
Layout
● Most common in the industry:
○ Left sidebar for navigation
○ Widest column for for main content (right in a 2-column design,
middle in a 3-column design)
● Keep the focus on the most important information:
○ Closable sidebars
○ The possibility to open parts of the page in fullscreen mode
○ Use only the most important components as fixed elements
● White space
Sample Design
How to contact me….
LinkedIn: linkedin.com/in/ilonakd
Email: ilona@ikd.io
Discord and GitHub: cycene

More Related Content

What's hot

10 Tips to Pass Salesforce Security Review (and Steps to Take If You Don’t!)
10 Tips to Pass Salesforce Security Review (and Steps to Take If You Don’t!)10 Tips to Pass Salesforce Security Review (and Steps to Take If You Don’t!)
10 Tips to Pass Salesforce Security Review (and Steps to Take If You Don’t!)CodeScience
 
HP Software Performance Tour 2014 - Enterprise Agility in the age of Applicat...
HP Software Performance Tour 2014 - Enterprise Agility in the age of Applicat...HP Software Performance Tour 2014 - Enterprise Agility in the age of Applicat...
HP Software Performance Tour 2014 - Enterprise Agility in the age of Applicat...HP Enterprise Italia
 
INTERFACE, by apidays - Building an API-First organization by Ankit Sobti, P...
INTERFACE, by apidays  - Building an API-First organization by Ankit Sobti, P...INTERFACE, by apidays  - Building an API-First organization by Ankit Sobti, P...
INTERFACE, by apidays - Building an API-First organization by Ankit Sobti, P...apidays
 
Ready, Set, Deploy: How Place Technology Streamlined Deployment on the AppExc...
Ready, Set, Deploy: How Place Technology Streamlined Deployment on the AppExc...Ready, Set, Deploy: How Place Technology Streamlined Deployment on the AppExc...
Ready, Set, Deploy: How Place Technology Streamlined Deployment on the AppExc...CodeScience
 
Fireside Chat: How to build a winning investment management website
Fireside Chat: How to build a winning investment management websiteFireside Chat: How to build a winning investment management website
Fireside Chat: How to build a winning investment management websiteAppFolio
 
Smarter Tools for Modern Investment Management
Smarter Tools for Modern Investment ManagementSmarter Tools for Modern Investment Management
Smarter Tools for Modern Investment ManagementAppFolio
 
Partnership presentation (2)
Partnership presentation (2)Partnership presentation (2)
Partnership presentation (2)Synergetics India
 
Capital One: Bridging the Gap Between Quality Engineering and Product Managem...
Capital One: Bridging the Gap Between Quality Engineering and Product Managem...Capital One: Bridging the Gap Between Quality Engineering and Product Managem...
Capital One: Bridging the Gap Between Quality Engineering and Product Managem...Applitools
 
Agile skills creeks
Agile   skills creeksAgile   skills creeks
Agile skills creeksHany Darwish
 
Questions to ask before selecting a mobile app development company
Questions to ask before selecting a mobile app development company Questions to ask before selecting a mobile app development company
Questions to ask before selecting a mobile app development company Appinventiv
 
Does Agility Be Present Once You Apply It In Your Project
Does Agility Be Present Once You Apply It In Your ProjectDoes Agility Be Present Once You Apply It In Your Project
Does Agility Be Present Once You Apply It In Your ProjectEffOne_Technologies
 
Doing a GAP Analysis Before Choosing a New ERP
Doing a GAP Analysis Before Choosing a New ERPDoing a GAP Analysis Before Choosing a New ERP
Doing a GAP Analysis Before Choosing a New ERPOdoo
 
Lean wisdom - How to develop an insurance webshop in 6 months
Lean wisdom - How to develop an insurance webshop in 6 monthsLean wisdom - How to develop an insurance webshop in 6 months
Lean wisdom - How to develop an insurance webshop in 6 monthsPer Spilling
 
Silicon Valley Marketo User Group Meeting February 29, 2012
Silicon Valley Marketo User Group Meeting February 29, 2012Silicon Valley Marketo User Group Meeting February 29, 2012
Silicon Valley Marketo User Group Meeting February 29, 2012ryanvong
 
An insider's look at Appfolio's top property management features
An insider's look at Appfolio's top property management features An insider's look at Appfolio's top property management features
An insider's look at Appfolio's top property management features AppFolio
 

What's hot (20)

10 Tips to Pass Salesforce Security Review (and Steps to Take If You Don’t!)
10 Tips to Pass Salesforce Security Review (and Steps to Take If You Don’t!)10 Tips to Pass Salesforce Security Review (and Steps to Take If You Don’t!)
10 Tips to Pass Salesforce Security Review (and Steps to Take If You Don’t!)
 
HP Software Performance Tour 2014 - Enterprise Agility in the age of Applicat...
HP Software Performance Tour 2014 - Enterprise Agility in the age of Applicat...HP Software Performance Tour 2014 - Enterprise Agility in the age of Applicat...
HP Software Performance Tour 2014 - Enterprise Agility in the age of Applicat...
 
INTERFACE, by apidays - Building an API-First organization by Ankit Sobti, P...
INTERFACE, by apidays  - Building an API-First organization by Ankit Sobti, P...INTERFACE, by apidays  - Building an API-First organization by Ankit Sobti, P...
INTERFACE, by apidays - Building an API-First organization by Ankit Sobti, P...
 
Ready, Set, Deploy: How Place Technology Streamlined Deployment on the AppExc...
Ready, Set, Deploy: How Place Technology Streamlined Deployment on the AppExc...Ready, Set, Deploy: How Place Technology Streamlined Deployment on the AppExc...
Ready, Set, Deploy: How Place Technology Streamlined Deployment on the AppExc...
 
Fireside Chat: How to build a winning investment management website
Fireside Chat: How to build a winning investment management websiteFireside Chat: How to build a winning investment management website
Fireside Chat: How to build a winning investment management website
 
Smarter Tools for Modern Investment Management
Smarter Tools for Modern Investment ManagementSmarter Tools for Modern Investment Management
Smarter Tools for Modern Investment Management
 
Partnership presentation (2)
Partnership presentation (2)Partnership presentation (2)
Partnership presentation (2)
 
Capital One: Bridging the Gap Between Quality Engineering and Product Managem...
Capital One: Bridging the Gap Between Quality Engineering and Product Managem...Capital One: Bridging the Gap Between Quality Engineering and Product Managem...
Capital One: Bridging the Gap Between Quality Engineering and Product Managem...
 
Agile skills creeks
Agile   skills creeksAgile   skills creeks
Agile skills creeks
 
Questions to ask before selecting a mobile app development company
Questions to ask before selecting a mobile app development company Questions to ask before selecting a mobile app development company
Questions to ask before selecting a mobile app development company
 
Does Agility Be Present Once You Apply It In Your Project
Does Agility Be Present Once You Apply It In Your ProjectDoes Agility Be Present Once You Apply It In Your Project
Does Agility Be Present Once You Apply It In Your Project
 
Doing a GAP Analysis Before Choosing a New ERP
Doing a GAP Analysis Before Choosing a New ERPDoing a GAP Analysis Before Choosing a New ERP
Doing a GAP Analysis Before Choosing a New ERP
 
Lean wisdom - How to develop an insurance webshop in 6 months
Lean wisdom - How to develop an insurance webshop in 6 monthsLean wisdom - How to develop an insurance webshop in 6 months
Lean wisdom - How to develop an insurance webshop in 6 months
 
Silicon Valley Marketo User Group Meeting February 29, 2012
Silicon Valley Marketo User Group Meeting February 29, 2012Silicon Valley Marketo User Group Meeting February 29, 2012
Silicon Valley Marketo User Group Meeting February 29, 2012
 
An insider's look at Appfolio's top property management features
An insider's look at Appfolio's top property management features An insider's look at Appfolio's top property management features
An insider's look at Appfolio's top property management features
 
Getty/IO - Business Presentation 2017
Getty/IO - Business Presentation 2017Getty/IO - Business Presentation 2017
Getty/IO - Business Presentation 2017
 
Tina Samaniego Resume
Tina Samaniego ResumeTina Samaniego Resume
Tina Samaniego Resume
 
Tina Samaniego Resume
Tina Samaniego ResumeTina Samaniego Resume
Tina Samaniego Resume
 
Tina Samaniego Resume
Tina Samaniego ResumeTina Samaniego Resume
Tina Samaniego Resume
 
Ecommerce website development uk
Ecommerce website development ukEcommerce website development uk
Ecommerce website development uk
 

Similar to DevRel Doc Experience API Days

Webinar: Build a Moat with Ecosystems & Marketplaces by Adobe Sr PM
Webinar: Build a Moat with Ecosystems & Marketplaces by Adobe Sr PMWebinar: Build a Moat with Ecosystems & Marketplaces by Adobe Sr PM
Webinar: Build a Moat with Ecosystems & Marketplaces by Adobe Sr PMProduct School
 
Transitioning to a Product Management Role by WeWork PM
Transitioning to a Product Management Role by WeWork PMTransitioning to a Product Management Role by WeWork PM
Transitioning to a Product Management Role by WeWork PMProduct School
 
Agile Gurugram 2016 | Conference | Demystifying DevOps | Uday Kumar
Agile Gurugram 2016 | Conference | Demystifying DevOps | Uday KumarAgile Gurugram 2016 | Conference | Demystifying DevOps | Uday Kumar
Agile Gurugram 2016 | Conference | Demystifying DevOps | Uday KumarAgileNetwork
 
Delivering Projects the Pivotal Way
Delivering Projects the Pivotal WayDelivering Projects the Pivotal Way
Delivering Projects the Pivotal WayAaron Severs
 
The Software Development Industry
The Software Development IndustryThe Software Development Industry
The Software Development IndustryOlivier Bourgeois
 
Contributing to Apache Projects and Making Profits
Contributing to Apache Projects and Making ProfitsContributing to Apache Projects and Making Profits
Contributing to Apache Projects and Making ProfitsHenry Saputra
 
Pull requests do's and don'ts
Pull requests do's and don'tsPull requests do's and don'ts
Pull requests do's and don'tsArie Bregman
 
Improving Accessibility for Higher Education
Improving Accessibility for Higher EducationImproving Accessibility for Higher Education
Improving Accessibility for Higher EducationAcquia
 
Odoo Implementation Methodology
Odoo Implementation MethodologyOdoo Implementation Methodology
Odoo Implementation MethodologyOdoo
 
Creating and Managing Technical Content for Open Source Products
Creating and Managing Technical Content for Open Source ProductsCreating and Managing Technical Content for Open Source Products
Creating and Managing Technical Content for Open Source ProductsWSO2
 
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by Ilona Ko...
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by  Ilona Ko...APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by  Ilona Ko...
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by Ilona Ko...apidays
 
Lessons Learned from Revamping Our Doc Site
Lessons Learned from Revamping Our Doc SiteLessons Learned from Revamping Our Doc Site
Lessons Learned from Revamping Our Doc SitePronovix
 
How to Become a Technical Product Manager by Goop.com Tech PM
How to Become a Technical Product Manager by Goop.com Tech PMHow to Become a Technical Product Manager by Goop.com Tech PM
How to Become a Technical Product Manager by Goop.com Tech PMProduct School
 
Kyivpy#8 - Quality Driven Development with Python
Kyivpy#8   - Quality Driven Development with PythonKyivpy#8   - Quality Driven Development with Python
Kyivpy#8 - Quality Driven Development with PythonMax Klymyshyn
 
Ba why development projects fail
Ba   why development projects failBa   why development projects fail
Ba why development projects failCTE Solutions Inc.
 
Discovery 101
Discovery 101Discovery 101
Discovery 101creed
 
Chase Tilton Interactive Resume
Chase Tilton Interactive ResumeChase Tilton Interactive Resume
Chase Tilton Interactive ResumeChaseTilton1
 
Balancing PM & Software Development Practices by Splunk Sr PM
Balancing PM & Software Development Practices by Splunk Sr PMBalancing PM & Software Development Practices by Splunk Sr PM
Balancing PM & Software Development Practices by Splunk Sr PMProduct School
 
Developer Experience as a Product
Developer Experience as a ProductDeveloper Experience as a Product
Developer Experience as a ProductPronovix
 

Similar to DevRel Doc Experience API Days (20)

Webinar: Build a Moat with Ecosystems & Marketplaces by Adobe Sr PM
Webinar: Build a Moat with Ecosystems & Marketplaces by Adobe Sr PMWebinar: Build a Moat with Ecosystems & Marketplaces by Adobe Sr PM
Webinar: Build a Moat with Ecosystems & Marketplaces by Adobe Sr PM
 
Transitioning to a Product Management Role by WeWork PM
Transitioning to a Product Management Role by WeWork PMTransitioning to a Product Management Role by WeWork PM
Transitioning to a Product Management Role by WeWork PM
 
Agile Gurugram 2016 | Conference | Demystifying DevOps | Uday Kumar
Agile Gurugram 2016 | Conference | Demystifying DevOps | Uday KumarAgile Gurugram 2016 | Conference | Demystifying DevOps | Uday Kumar
Agile Gurugram 2016 | Conference | Demystifying DevOps | Uday Kumar
 
Delivering Projects the Pivotal Way
Delivering Projects the Pivotal WayDelivering Projects the Pivotal Way
Delivering Projects the Pivotal Way
 
The Software Development Industry
The Software Development IndustryThe Software Development Industry
The Software Development Industry
 
Contributing to Apache Projects and Making Profits
Contributing to Apache Projects and Making ProfitsContributing to Apache Projects and Making Profits
Contributing to Apache Projects and Making Profits
 
Pull requests do's and don'ts
Pull requests do's and don'tsPull requests do's and don'ts
Pull requests do's and don'ts
 
Improving Accessibility for Higher Education
Improving Accessibility for Higher EducationImproving Accessibility for Higher Education
Improving Accessibility for Higher Education
 
Odoo Implementation Methodology
Odoo Implementation MethodologyOdoo Implementation Methodology
Odoo Implementation Methodology
 
Creating and Managing Technical Content for Open Source Products
Creating and Managing Technical Content for Open Source ProductsCreating and Managing Technical Content for Open Source Products
Creating and Managing Technical Content for Open Source Products
 
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by Ilona Ko...
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by  Ilona Ko...APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by  Ilona Ko...
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by Ilona Ko...
 
Lessons Learned from Revamping Our Doc Site
Lessons Learned from Revamping Our Doc SiteLessons Learned from Revamping Our Doc Site
Lessons Learned from Revamping Our Doc Site
 
How to Become a Technical Product Manager by Goop.com Tech PM
How to Become a Technical Product Manager by Goop.com Tech PMHow to Become a Technical Product Manager by Goop.com Tech PM
How to Become a Technical Product Manager by Goop.com Tech PM
 
Kyivpy#8 - Quality Driven Development with Python
Kyivpy#8   - Quality Driven Development with PythonKyivpy#8   - Quality Driven Development with Python
Kyivpy#8 - Quality Driven Development with Python
 
Designing in the open
Designing in the openDesigning in the open
Designing in the open
 
Ba why development projects fail
Ba   why development projects failBa   why development projects fail
Ba why development projects fail
 
Discovery 101
Discovery 101Discovery 101
Discovery 101
 
Chase Tilton Interactive Resume
Chase Tilton Interactive ResumeChase Tilton Interactive Resume
Chase Tilton Interactive Resume
 
Balancing PM & Software Development Practices by Splunk Sr PM
Balancing PM & Software Development Practices by Splunk Sr PMBalancing PM & Software Development Practices by Splunk Sr PM
Balancing PM & Software Development Practices by Splunk Sr PM
 
Developer Experience as a Product
Developer Experience as a ProductDeveloper Experience as a Product
Developer Experience as a Product
 

More from apidays

apidays Australia 2023 - A programmatic approach to API success including Ope...
apidays Australia 2023 - A programmatic approach to API success including Ope...apidays Australia 2023 - A programmatic approach to API success including Ope...
apidays Australia 2023 - A programmatic approach to API success including Ope...apidays
 
apidays Singapore 2023 - Addressing the Data Gap, Jerome Eger, Smile API
apidays Singapore 2023 - Addressing the Data Gap, Jerome Eger, Smile APIapidays Singapore 2023 - Addressing the Data Gap, Jerome Eger, Smile API
apidays Singapore 2023 - Addressing the Data Gap, Jerome Eger, Smile APIapidays
 
apidays Singapore 2023 - Iterate Faster with Dynamic Flows, Yee Hui Poh, Wise
apidays Singapore 2023 - Iterate Faster with Dynamic Flows, Yee Hui Poh, Wiseapidays Singapore 2023 - Iterate Faster with Dynamic Flows, Yee Hui Poh, Wise
apidays Singapore 2023 - Iterate Faster with Dynamic Flows, Yee Hui Poh, Wiseapidays
 
apidays Singapore 2023 - Banking the Ecosystem, Apurv Suri, SC Ventures
apidays Singapore 2023 - Banking the Ecosystem, Apurv Suri, SC Venturesapidays Singapore 2023 - Banking the Ecosystem, Apurv Suri, SC Ventures
apidays Singapore 2023 - Banking the Ecosystem, Apurv Suri, SC Venturesapidays
 
apidays Singapore 2023 - Digitalising agreements with data, design & technolo...
apidays Singapore 2023 - Digitalising agreements with data, design & technolo...apidays Singapore 2023 - Digitalising agreements with data, design & technolo...
apidays Singapore 2023 - Digitalising agreements with data, design & technolo...apidays
 
apidays Singapore 2023 - Building a digital-first investment management model...
apidays Singapore 2023 - Building a digital-first investment management model...apidays Singapore 2023 - Building a digital-first investment management model...
apidays Singapore 2023 - Building a digital-first investment management model...apidays
 
apidays Singapore 2023 - Changing the culture of building software, Aman Dham...
apidays Singapore 2023 - Changing the culture of building software, Aman Dham...apidays Singapore 2023 - Changing the culture of building software, Aman Dham...
apidays Singapore 2023 - Changing the culture of building software, Aman Dham...apidays
 
apidays Singapore 2023 - Connecting the trade ecosystem, CHOO Wai Yee, Singap...
apidays Singapore 2023 - Connecting the trade ecosystem, CHOO Wai Yee, Singap...apidays Singapore 2023 - Connecting the trade ecosystem, CHOO Wai Yee, Singap...
apidays Singapore 2023 - Connecting the trade ecosystem, CHOO Wai Yee, Singap...apidays
 
apidays Singapore 2023 - Beyond REST, Claudio Tag, IBM
apidays Singapore 2023 - Beyond REST, Claudio Tag, IBMapidays Singapore 2023 - Beyond REST, Claudio Tag, IBM
apidays Singapore 2023 - Beyond REST, Claudio Tag, IBMapidays
 
apidays Singapore 2023 - Securing and protecting our digital way of life, Ver...
apidays Singapore 2023 - Securing and protecting our digital way of life, Ver...apidays Singapore 2023 - Securing and protecting our digital way of life, Ver...
apidays Singapore 2023 - Securing and protecting our digital way of life, Ver...apidays
 
apidays Singapore 2023 - State of the API Industry, Manjunath Bhat, Gartner
apidays Singapore 2023 - State of the API Industry, Manjunath Bhat, Gartnerapidays Singapore 2023 - State of the API Industry, Manjunath Bhat, Gartner
apidays Singapore 2023 - State of the API Industry, Manjunath Bhat, Gartnerapidays
 
apidays Australia 2023 - Curb your Enthusiasm:Sustainable Scaling of APIs, Sa...
apidays Australia 2023 - Curb your Enthusiasm:Sustainable Scaling of APIs, Sa...apidays Australia 2023 - Curb your Enthusiasm:Sustainable Scaling of APIs, Sa...
apidays Australia 2023 - Curb your Enthusiasm:Sustainable Scaling of APIs, Sa...apidays
 
Apidays Paris 2023 - API Security Challenges for Cloud-native Software Archit...
Apidays Paris 2023 - API Security Challenges for Cloud-native Software Archit...Apidays Paris 2023 - API Security Challenges for Cloud-native Software Archit...
Apidays Paris 2023 - API Security Challenges for Cloud-native Software Archit...apidays
 
Apidays Paris 2023 - State of Tech Sustainability 2023, Gaël Duez, Green IO
Apidays Paris 2023 - State of Tech Sustainability 2023, Gaël Duez, Green IOApidays Paris 2023 - State of Tech Sustainability 2023, Gaël Duez, Green IO
Apidays Paris 2023 - State of Tech Sustainability 2023, Gaël Duez, Green IOapidays
 
Apidays Paris 2023 - 7 Mistakes When Putting In Place An API Program, Francoi...
Apidays Paris 2023 - 7 Mistakes When Putting In Place An API Program, Francoi...Apidays Paris 2023 - 7 Mistakes When Putting In Place An API Program, Francoi...
Apidays Paris 2023 - 7 Mistakes When Putting In Place An API Program, Francoi...apidays
 
Apidays Paris 2023 - Building APIs That Developers Love: Feedback Collection ...
Apidays Paris 2023 - Building APIs That Developers Love: Feedback Collection ...Apidays Paris 2023 - Building APIs That Developers Love: Feedback Collection ...
Apidays Paris 2023 - Building APIs That Developers Love: Feedback Collection ...apidays
 
Apidays Paris 2023 - Product Managers and API Documentation, Gareth Faull, Lo...
Apidays Paris 2023 - Product Managers and API Documentation, Gareth Faull, Lo...Apidays Paris 2023 - Product Managers and API Documentation, Gareth Faull, Lo...
Apidays Paris 2023 - Product Managers and API Documentation, Gareth Faull, Lo...apidays
 
Apidays Paris 2023 - How to use NoCode as a Microservice, Benjamin Buléon and...
Apidays Paris 2023 - How to use NoCode as a Microservice, Benjamin Buléon and...Apidays Paris 2023 - How to use NoCode as a Microservice, Benjamin Buléon and...
Apidays Paris 2023 - How to use NoCode as a Microservice, Benjamin Buléon and...apidays
 
Apidays Paris 2023 - Boosting Event-Driven Development with AsyncAPI and Micr...
Apidays Paris 2023 - Boosting Event-Driven Development with AsyncAPI and Micr...Apidays Paris 2023 - Boosting Event-Driven Development with AsyncAPI and Micr...
Apidays Paris 2023 - Boosting Event-Driven Development with AsyncAPI and Micr...apidays
 
Apidays Paris 2023 - API Observability: Improving Governance, Security and Op...
Apidays Paris 2023 - API Observability: Improving Governance, Security and Op...Apidays Paris 2023 - API Observability: Improving Governance, Security and Op...
Apidays Paris 2023 - API Observability: Improving Governance, Security and Op...apidays
 

More from apidays (20)

apidays Australia 2023 - A programmatic approach to API success including Ope...
apidays Australia 2023 - A programmatic approach to API success including Ope...apidays Australia 2023 - A programmatic approach to API success including Ope...
apidays Australia 2023 - A programmatic approach to API success including Ope...
 
apidays Singapore 2023 - Addressing the Data Gap, Jerome Eger, Smile API
apidays Singapore 2023 - Addressing the Data Gap, Jerome Eger, Smile APIapidays Singapore 2023 - Addressing the Data Gap, Jerome Eger, Smile API
apidays Singapore 2023 - Addressing the Data Gap, Jerome Eger, Smile API
 
apidays Singapore 2023 - Iterate Faster with Dynamic Flows, Yee Hui Poh, Wise
apidays Singapore 2023 - Iterate Faster with Dynamic Flows, Yee Hui Poh, Wiseapidays Singapore 2023 - Iterate Faster with Dynamic Flows, Yee Hui Poh, Wise
apidays Singapore 2023 - Iterate Faster with Dynamic Flows, Yee Hui Poh, Wise
 
apidays Singapore 2023 - Banking the Ecosystem, Apurv Suri, SC Ventures
apidays Singapore 2023 - Banking the Ecosystem, Apurv Suri, SC Venturesapidays Singapore 2023 - Banking the Ecosystem, Apurv Suri, SC Ventures
apidays Singapore 2023 - Banking the Ecosystem, Apurv Suri, SC Ventures
 
apidays Singapore 2023 - Digitalising agreements with data, design & technolo...
apidays Singapore 2023 - Digitalising agreements with data, design & technolo...apidays Singapore 2023 - Digitalising agreements with data, design & technolo...
apidays Singapore 2023 - Digitalising agreements with data, design & technolo...
 
apidays Singapore 2023 - Building a digital-first investment management model...
apidays Singapore 2023 - Building a digital-first investment management model...apidays Singapore 2023 - Building a digital-first investment management model...
apidays Singapore 2023 - Building a digital-first investment management model...
 
apidays Singapore 2023 - Changing the culture of building software, Aman Dham...
apidays Singapore 2023 - Changing the culture of building software, Aman Dham...apidays Singapore 2023 - Changing the culture of building software, Aman Dham...
apidays Singapore 2023 - Changing the culture of building software, Aman Dham...
 
apidays Singapore 2023 - Connecting the trade ecosystem, CHOO Wai Yee, Singap...
apidays Singapore 2023 - Connecting the trade ecosystem, CHOO Wai Yee, Singap...apidays Singapore 2023 - Connecting the trade ecosystem, CHOO Wai Yee, Singap...
apidays Singapore 2023 - Connecting the trade ecosystem, CHOO Wai Yee, Singap...
 
apidays Singapore 2023 - Beyond REST, Claudio Tag, IBM
apidays Singapore 2023 - Beyond REST, Claudio Tag, IBMapidays Singapore 2023 - Beyond REST, Claudio Tag, IBM
apidays Singapore 2023 - Beyond REST, Claudio Tag, IBM
 
apidays Singapore 2023 - Securing and protecting our digital way of life, Ver...
apidays Singapore 2023 - Securing and protecting our digital way of life, Ver...apidays Singapore 2023 - Securing and protecting our digital way of life, Ver...
apidays Singapore 2023 - Securing and protecting our digital way of life, Ver...
 
apidays Singapore 2023 - State of the API Industry, Manjunath Bhat, Gartner
apidays Singapore 2023 - State of the API Industry, Manjunath Bhat, Gartnerapidays Singapore 2023 - State of the API Industry, Manjunath Bhat, Gartner
apidays Singapore 2023 - State of the API Industry, Manjunath Bhat, Gartner
 
apidays Australia 2023 - Curb your Enthusiasm:Sustainable Scaling of APIs, Sa...
apidays Australia 2023 - Curb your Enthusiasm:Sustainable Scaling of APIs, Sa...apidays Australia 2023 - Curb your Enthusiasm:Sustainable Scaling of APIs, Sa...
apidays Australia 2023 - Curb your Enthusiasm:Sustainable Scaling of APIs, Sa...
 
Apidays Paris 2023 - API Security Challenges for Cloud-native Software Archit...
Apidays Paris 2023 - API Security Challenges for Cloud-native Software Archit...Apidays Paris 2023 - API Security Challenges for Cloud-native Software Archit...
Apidays Paris 2023 - API Security Challenges for Cloud-native Software Archit...
 
Apidays Paris 2023 - State of Tech Sustainability 2023, Gaël Duez, Green IO
Apidays Paris 2023 - State of Tech Sustainability 2023, Gaël Duez, Green IOApidays Paris 2023 - State of Tech Sustainability 2023, Gaël Duez, Green IO
Apidays Paris 2023 - State of Tech Sustainability 2023, Gaël Duez, Green IO
 
Apidays Paris 2023 - 7 Mistakes When Putting In Place An API Program, Francoi...
Apidays Paris 2023 - 7 Mistakes When Putting In Place An API Program, Francoi...Apidays Paris 2023 - 7 Mistakes When Putting In Place An API Program, Francoi...
Apidays Paris 2023 - 7 Mistakes When Putting In Place An API Program, Francoi...
 
Apidays Paris 2023 - Building APIs That Developers Love: Feedback Collection ...
Apidays Paris 2023 - Building APIs That Developers Love: Feedback Collection ...Apidays Paris 2023 - Building APIs That Developers Love: Feedback Collection ...
Apidays Paris 2023 - Building APIs That Developers Love: Feedback Collection ...
 
Apidays Paris 2023 - Product Managers and API Documentation, Gareth Faull, Lo...
Apidays Paris 2023 - Product Managers and API Documentation, Gareth Faull, Lo...Apidays Paris 2023 - Product Managers and API Documentation, Gareth Faull, Lo...
Apidays Paris 2023 - Product Managers and API Documentation, Gareth Faull, Lo...
 
Apidays Paris 2023 - How to use NoCode as a Microservice, Benjamin Buléon and...
Apidays Paris 2023 - How to use NoCode as a Microservice, Benjamin Buléon and...Apidays Paris 2023 - How to use NoCode as a Microservice, Benjamin Buléon and...
Apidays Paris 2023 - How to use NoCode as a Microservice, Benjamin Buléon and...
 
Apidays Paris 2023 - Boosting Event-Driven Development with AsyncAPI and Micr...
Apidays Paris 2023 - Boosting Event-Driven Development with AsyncAPI and Micr...Apidays Paris 2023 - Boosting Event-Driven Development with AsyncAPI and Micr...
Apidays Paris 2023 - Boosting Event-Driven Development with AsyncAPI and Micr...
 
Apidays Paris 2023 - API Observability: Improving Governance, Security and Op...
Apidays Paris 2023 - API Observability: Improving Governance, Security and Op...Apidays Paris 2023 - API Observability: Improving Governance, Security and Op...
Apidays Paris 2023 - API Observability: Improving Governance, Security and Op...
 

Recently uploaded

Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmatics
Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmaticsKotlin Multiplatform & Compose Multiplatform - Starter kit for pragmatics
Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmaticsAndrey Dotsenko
 
Bluetooth Controlled Car with Arduino.pdf
Bluetooth Controlled Car with Arduino.pdfBluetooth Controlled Car with Arduino.pdf
Bluetooth Controlled Car with Arduino.pdfngoud9212
 
Are Multi-Cloud and Serverless Good or Bad?
Are Multi-Cloud and Serverless Good or Bad?Are Multi-Cloud and Serverless Good or Bad?
Are Multi-Cloud and Serverless Good or Bad?Mattias Andersson
 
Unleash Your Potential - Namagunga Girls Coding Club
Unleash Your Potential - Namagunga Girls Coding ClubUnleash Your Potential - Namagunga Girls Coding Club
Unleash Your Potential - Namagunga Girls Coding ClubKalema Edgar
 
"LLMs for Python Engineers: Advanced Data Analysis and Semantic Kernel",Oleks...
"LLMs for Python Engineers: Advanced Data Analysis and Semantic Kernel",Oleks..."LLMs for Python Engineers: Advanced Data Analysis and Semantic Kernel",Oleks...
"LLMs for Python Engineers: Advanced Data Analysis and Semantic Kernel",Oleks...Fwdays
 
Designing IA for AI - Information Architecture Conference 2024
Designing IA for AI - Information Architecture Conference 2024Designing IA for AI - Information Architecture Conference 2024
Designing IA for AI - Information Architecture Conference 2024Enterprise Knowledge
 
"Federated learning: out of reach no matter how close",Oleksandr Lapshyn
"Federated learning: out of reach no matter how close",Oleksandr Lapshyn"Federated learning: out of reach no matter how close",Oleksandr Lapshyn
"Federated learning: out of reach no matter how close",Oleksandr LapshynFwdays
 
Unlocking the Potential of the Cloud for IBM Power Systems
Unlocking the Potential of the Cloud for IBM Power SystemsUnlocking the Potential of the Cloud for IBM Power Systems
Unlocking the Potential of the Cloud for IBM Power SystemsPrecisely
 
SQL Database Design For Developers at php[tek] 2024
SQL Database Design For Developers at php[tek] 2024SQL Database Design For Developers at php[tek] 2024
SQL Database Design For Developers at php[tek] 2024Scott Keck-Warren
 
CloudStudio User manual (basic edition):
CloudStudio User manual (basic edition):CloudStudio User manual (basic edition):
CloudStudio User manual (basic edition):comworks
 
Connect Wave/ connectwave Pitch Deck Presentation
Connect Wave/ connectwave Pitch Deck PresentationConnect Wave/ connectwave Pitch Deck Presentation
Connect Wave/ connectwave Pitch Deck PresentationSlibray Presentation
 
Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmatics
Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmaticsKotlin Multiplatform & Compose Multiplatform - Starter kit for pragmatics
Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmaticscarlostorres15106
 
My Hashitalk Indonesia April 2024 Presentation
My Hashitalk Indonesia April 2024 PresentationMy Hashitalk Indonesia April 2024 Presentation
My Hashitalk Indonesia April 2024 PresentationRidwan Fadjar
 
New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024
New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024
New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024BookNet Canada
 
Build your next Gen AI Breakthrough - April 2024
Build your next Gen AI Breakthrough - April 2024Build your next Gen AI Breakthrough - April 2024
Build your next Gen AI Breakthrough - April 2024Neo4j
 
Transcript: New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024
Transcript: New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024Transcript: New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024
Transcript: New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024BookNet Canada
 
Artificial intelligence in the post-deep learning era
Artificial intelligence in the post-deep learning eraArtificial intelligence in the post-deep learning era
Artificial intelligence in the post-deep learning eraDeakin University
 

Recently uploaded (20)

Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmatics
Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmaticsKotlin Multiplatform & Compose Multiplatform - Starter kit for pragmatics
Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmatics
 
Bluetooth Controlled Car with Arduino.pdf
Bluetooth Controlled Car with Arduino.pdfBluetooth Controlled Car with Arduino.pdf
Bluetooth Controlled Car with Arduino.pdf
 
Are Multi-Cloud and Serverless Good or Bad?
Are Multi-Cloud and Serverless Good or Bad?Are Multi-Cloud and Serverless Good or Bad?
Are Multi-Cloud and Serverless Good or Bad?
 
Unleash Your Potential - Namagunga Girls Coding Club
Unleash Your Potential - Namagunga Girls Coding ClubUnleash Your Potential - Namagunga Girls Coding Club
Unleash Your Potential - Namagunga Girls Coding Club
 
"LLMs for Python Engineers: Advanced Data Analysis and Semantic Kernel",Oleks...
"LLMs for Python Engineers: Advanced Data Analysis and Semantic Kernel",Oleks..."LLMs for Python Engineers: Advanced Data Analysis and Semantic Kernel",Oleks...
"LLMs for Python Engineers: Advanced Data Analysis and Semantic Kernel",Oleks...
 
Designing IA for AI - Information Architecture Conference 2024
Designing IA for AI - Information Architecture Conference 2024Designing IA for AI - Information Architecture Conference 2024
Designing IA for AI - Information Architecture Conference 2024
 
"Federated learning: out of reach no matter how close",Oleksandr Lapshyn
"Federated learning: out of reach no matter how close",Oleksandr Lapshyn"Federated learning: out of reach no matter how close",Oleksandr Lapshyn
"Federated learning: out of reach no matter how close",Oleksandr Lapshyn
 
Hot Sexy call girls in Panjabi Bagh 🔝 9953056974 🔝 Delhi escort Service
Hot Sexy call girls in Panjabi Bagh 🔝 9953056974 🔝 Delhi escort ServiceHot Sexy call girls in Panjabi Bagh 🔝 9953056974 🔝 Delhi escort Service
Hot Sexy call girls in Panjabi Bagh 🔝 9953056974 🔝 Delhi escort Service
 
DMCC Future of Trade Web3 - Special Edition
DMCC Future of Trade Web3 - Special EditionDMCC Future of Trade Web3 - Special Edition
DMCC Future of Trade Web3 - Special Edition
 
Unlocking the Potential of the Cloud for IBM Power Systems
Unlocking the Potential of the Cloud for IBM Power SystemsUnlocking the Potential of the Cloud for IBM Power Systems
Unlocking the Potential of the Cloud for IBM Power Systems
 
SQL Database Design For Developers at php[tek] 2024
SQL Database Design For Developers at php[tek] 2024SQL Database Design For Developers at php[tek] 2024
SQL Database Design For Developers at php[tek] 2024
 
CloudStudio User manual (basic edition):
CloudStudio User manual (basic edition):CloudStudio User manual (basic edition):
CloudStudio User manual (basic edition):
 
Connect Wave/ connectwave Pitch Deck Presentation
Connect Wave/ connectwave Pitch Deck PresentationConnect Wave/ connectwave Pitch Deck Presentation
Connect Wave/ connectwave Pitch Deck Presentation
 
Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmatics
Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmaticsKotlin Multiplatform & Compose Multiplatform - Starter kit for pragmatics
Kotlin Multiplatform & Compose Multiplatform - Starter kit for pragmatics
 
My Hashitalk Indonesia April 2024 Presentation
My Hashitalk Indonesia April 2024 PresentationMy Hashitalk Indonesia April 2024 Presentation
My Hashitalk Indonesia April 2024 Presentation
 
New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024
New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024
New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024
 
Build your next Gen AI Breakthrough - April 2024
Build your next Gen AI Breakthrough - April 2024Build your next Gen AI Breakthrough - April 2024
Build your next Gen AI Breakthrough - April 2024
 
Transcript: New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024
Transcript: New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024Transcript: New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024
Transcript: New from BookNet Canada for 2024: BNC BiblioShare - Tech Forum 2024
 
Artificial intelligence in the post-deep learning era
Artificial intelligence in the post-deep learning eraArtificial intelligence in the post-deep learning era
Artificial intelligence in the post-deep learning era
 
Vulnerability_Management_GRC_by Sohang Sengupta.pptx
Vulnerability_Management_GRC_by Sohang Sengupta.pptxVulnerability_Management_GRC_by Sohang Sengupta.pptx
Vulnerability_Management_GRC_by Sohang Sengupta.pptx
 

DevRel Doc Experience API Days

  • 1. Doc Well for DevRel API Days Interface June 2020 Ilona Koren-Deutsch Technical Documentation Manager, Twitch
  • 2. About me ● None of my degrees are in anything to do with software. ● I’ve been a technical writer for about 25 years, not counting detours as a support engineer, curriculum developer, and chef (garde manger then chef de cuisine). ● I am a strong believer in the value of taking sabbaticals.
  • 3. About my job ● I’m on the Developer Relations team. ● In the past I have mostly been part of engineering teams, once curriculum development, and once support. ● There are clear differences.
  • 5. Pros ● Firsthand knowledge of product (and changes/deadlines) ● JIRA ● Close relationship with developers and dev managers Tech writing in Engineering Cons ● No big-picture view of doc UX ● No customer contact ● Tendency towards silos
  • 6. Pros ● Customer contact ● See documentation in use by own team ● Whole product view ● KB/articles Tech writing in Support Cons ● Unhappy-customer contact ● Lack of access to product before release
  • 7. Tech writing in Developer Relations Pros ● Direct access to customers ● Beta testing ● Varied content ● Building the doc experience Cons ● Customers have direct access to me ● “Business brain”
  • 8. Building the doc experience
  • 9. ● All the information that documents the API: ○ Getting started or onboarding pages ○ References ○ SDKs ○ Guides ○ FAQs ○ Tutorials Documentation
  • 10. What makes good developer documentation? ● Good organization ● Clear explanations ● Examples ● Consistency ● Interactive way to try API calls ● Comments section ● Support resources
  • 11. What makes a good portal? ● How well it helps users understand the API ● How it establishes trust ● The ways in which it helps developers quickly start using the API ● The quality of the API reference ● What forms of support it offers
  • 12. Understand the API ● Consider the audience ○ Developer looking to get started: the newcomer ○ Developer debugging a specific issue in an existing client: the debugger ○ CTO evaluating competing APIs: the decision maker ○ Product manager figuring out if X is possible with the API: the searcher ● Include use cases and success stories
  • 13. Establish trust ● Intuitive site architecture ● Navigation and search ● Changelog ● API monitor or dashboard ● Roadmap for upcoming features ● Terms of use
  • 14. Accelerate “Time to Hello World” ● Registration process ● Developer onboarding: ○ Getting started guide ○ Tutorials ○ Videos ○ Code samples
  • 15. API reference ● Authentication ● Status codes ● Error handling ● Sample code ● Example requests and responses
  • 16. Provide support ● Support from the company: ○ Contact form ○ Twitter ○ Public NDA Slack ● Community support: ○ Forums ○ Meetups
  • 19. Keep adding content ● Documentation updates ● Blog posts ● Videos ● Event postings
  • 20. Content-driven ● Design should underline your message ● Reduce frustration ● Do your user research
  • 21. Navigation ● Navigation always visible ○ Top navigation ○ Fixed sticky navigation ○ Sidebar navigation, either fixed or openable/closable ● Page titles and breadcrumbs ● Provide suggestions of where to go next ○ Related content ○ Previous/next buttons ● Search available on every page
  • 22. Layout ● Most common in the industry: ○ Left sidebar for navigation ○ Widest column for for main content (right in a 2-column design, middle in a 3-column design) ● Keep the focus on the most important information: ○ Closable sidebars ○ The possibility to open parts of the page in fullscreen mode ○ Use only the most important components as fixed elements ● White space
  • 24.
  • 25. How to contact me…. LinkedIn: linkedin.com/in/ilonakd Email: ilona@ikd.io Discord and GitHub: cycene