SlideShare a Scribd company logo
1 of 33
Download to read offline
API Documentation for
Diverse Communities
Alec Clews
API The Docs
Oct 2022
I am speaking to you from the lands of
the Wurundjeri people of the Kulin
Nation and I wish to acknowledge them
as Traditional Owners.
I would also like to pay my respects to
their Elders, past and present.
+
More information on
Acknowledgement To Country here
Acknowledgement of country
► Old school software nerd
► Works as a developer relations advocate at
PaperCut Software
► Loves technology and coffee
@alecthegeek
alecthegeek alecthegeek
https://www.linkedin.com/in/alecclews/
► Pronouns: He/Him
Who is Alec?
Why is API Docs Accessibility Important?
Poorly understood API docs
Increase support costs
Cultural and individual
characteristics affect
UNDERSTANDING
and
Reduce the number of people
using your API
We can fix this problem
It’s Easy! Write Docs with:
1. Intention
2. Empathy
Culture?
Culture has dimensions
Importantly
► Societal
► The individual
► Organisational
Cultural "Markers"
► The primary Written and
Spoken language
► "shared patterns of behaviors
and interactions, cognitive
constructs, and affective
understanding.."
Center for Advanced Research on
Language Acquisition,
University of Minnesota
Cultural "Markers" in Software Dev Teams
► Product development approach
(processes & maturity)
► Relationship with customers
► Domain of business expertise
► Technology choices
NOT JUST REFERENCE MATERIAL. For instance
What is API documentation?
API reference
Introductions and Concepts
Getting Started guides
Task & Story Based Explanations
Troubleshooting guides...
Technical Writing Here!
Sample Code
Creating Explanatory Content
Use Existing Best Practices
Write Accessible Content
“Accessible writing is good writing. It makes your
content easier for everyone to consume.”
– Blackboard
Write for Global Audiences. See:
► Google developer documentation style guide
► Microsoft Writing Style Guide
► IBM Style Guide ch 8
► Apple Style Guide
https://illlustrations.co/
Write Supplementary Material
► Your technology choices may be unfamiliar to many
► Provide additional material in blogs and knowledge bases
► Stops cluttering up API docs with details
► Get additional value from content
● This is one of our most popular posts ⇒
Creating API related Content
Use More Diagrams
"One Picture is Worth a Thousand
Words"
"One Diagram Illuminates 500
Words"
Useful for:
► System Components, their
Relationships & Deployment
► Sequences of events and API
calls
► Workflows & processes ...
► Diagrams are the ALT tag for to
SUPPORT the text
► Still provide complete
explanations
● & proper ALT tags on all images
► See Docs for Developers An Engineer’s Field
Guide to Technical Writing Ch 6
Example: Application Programming Interface
► Contract between two pieces of software a.k.a
specification. Provides information about:
● What can the clients request (1)?
● What will the server do?
● What will the server send back (2)?
● What can go wrong (3)?
Other Media
E.g. Videos, images, animated GIFs
Use carefully!
Issues
► Accessibility
► Harder to keep updated
► Hard to translate
But …
Sometimes best because:
► Video can illustrate complex
procedures
► An image highlights pertinent
information
Translation
► It's hard to translate technical
docs:
● They change frequently
● Manual translation takes
time and is expensive
► Controlled natural languages
can make translation easier
► Machine Translation may not be
good enough
► Your readers will probably
paste your content into Google
Translate anyway.
API reference content
API Reference Docs via Spec files
► Network API docs can also be generated from specification files
► Examples
● RESTful — Open API Specification (a.k.a. Swagger)
● gRPC — Protocol Buffers
● GraphQL — schema files
● XML-RPC — Write it by hand
API Reference Docs via source code
► Can be generated directly from source code comments and declarations
► Utility varies -- need to work within tool constraints
► Examples
● Go -- Godoc
● Java -- Javadoc
● Python -- Docstrings
● .NET C# -- XML documentation comments
API Reference Docs
Apply your API Style Guide to reference docs as well
► Names (functions, parameters and types)
► Consistent use of terms, explanations
► Simple clear descriptions and summaries
Inline Code “Snippets”
► Show individual API calls and responses
► Like diagrams, they support the text
► Important
► But often overused
● No Context
● Syntax, but no semantics
Provide Complete, Working, Code Solutions
Show me! Don't tell me!
► A concrete way to answer
questions
► Builds confidence with
quickstart
Beware: Dev language is a cultural
choice
Don't expect your audience to
download and run it without
prompting
Include:
► Exception handling
► Complex API requests and
corresponding responses
► API set up and tear down as
needed
► Well written code comments
Connecting with Your Development Partners
"Modern Agile" API Doc Delivery
► Delivered online
► Frequent and rapid updates
► Continuous iteration and
improvement
► Engaged Online Communities
► Pull vs Push
Other dev teams have different needs
► Stability
► Clear signals
► Regular release cadence
► Formal delivery of assets
(e.g. PDF)
► Passive consumption vs active
engagement
Try and meet people half way
Differences in Communication Style
► Some cultures prefer person to
person relationship
► Development teams (and
others) are not familiar with
support desk software and
processes
► Fear of being misunderstood
may result in long follow up PDF
attachments (which can be
hard to use and respond to)
► Public forums (e.g. Google
groups) may be blocked
Top Tip
PDF Distribution Tool
https://qrdoc.io/
QR Doc is a free service from PaperCut Software that allows you
distribute PDF documents and keep them up to date
Further Information
Additional Resources
► Accessible content Google developer documentation style guide
► Make text content readable and understandable W3 Web Content
Accessibility Guidelines (WCAG)
► Mozilla Developer network notes on WCAG
► 5 Tips To Improve Technical Writing For An International
Audience on LiNUX.COM
Resources contd:
► Translation, Localization, and Globalization from the Technical
Communication Body of Knowledge
► Testing your Documentation
► Controlled Natural Language Special Interest Group
► Easy English
► User-Friendly Documentations With Simplified Technical English
from Help Authoring Soft
Thank
you

More Related Content

Similar to Creating API documentation for international communities

The Concept Of Abstract Data Types
The Concept Of Abstract Data TypesThe Concept Of Abstract Data Types
The Concept Of Abstract Data Types
Katy Allen
 
Stream SQL eventflow visual programming for real programmers presentation
Stream SQL eventflow visual programming for real programmers presentationStream SQL eventflow visual programming for real programmers presentation
Stream SQL eventflow visual programming for real programmers presentation
streambase
 
Model-driven and low-code development for event-based systems | Bobby Calderw...
Model-driven and low-code development for event-based systems | Bobby Calderw...Model-driven and low-code development for event-based systems | Bobby Calderw...
Model-driven and low-code development for event-based systems | Bobby Calderw...
HostedbyConfluent
 

Similar to Creating API documentation for international communities (20)

The Concept Of Abstract Data Types
The Concept Of Abstract Data TypesThe Concept Of Abstract Data Types
The Concept Of Abstract Data Types
 
APIdays Helsinki 2019 - How API Will Help Win the Deals - the Case of Infrast...
APIdays Helsinki 2019 - How API Will Help Win the Deals - the Case of Infrast...APIdays Helsinki 2019 - How API Will Help Win the Deals - the Case of Infrast...
APIdays Helsinki 2019 - How API Will Help Win the Deals - the Case of Infrast...
 
UiPath Document Understanding_Day 3.pptx
UiPath Document Understanding_Day 3.pptxUiPath Document Understanding_Day 3.pptx
UiPath Document Understanding_Day 3.pptx
 
Breaking Through The Challenges of Scalable Deep Learning for Video Analytics
Breaking Through The Challenges of Scalable Deep Learning for Video AnalyticsBreaking Through The Challenges of Scalable Deep Learning for Video Analytics
Breaking Through The Challenges of Scalable Deep Learning for Video Analytics
 
Stream SQL eventflow visual programming for real programmers presentation
Stream SQL eventflow visual programming for real programmers presentationStream SQL eventflow visual programming for real programmers presentation
Stream SQL eventflow visual programming for real programmers presentation
 
IC-SDV 2019: Down-to-earth machine learning: What you always wanted your data...
IC-SDV 2019: Down-to-earth machine learning: What you always wanted your data...IC-SDV 2019: Down-to-earth machine learning: What you always wanted your data...
IC-SDV 2019: Down-to-earth machine learning: What you always wanted your data...
 
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The QuestionJDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
 
AIM | HDC 2016 Globalization As a Service
AIM | HDC 2016 Globalization As a ServiceAIM | HDC 2016 Globalization As a Service
AIM | HDC 2016 Globalization As a Service
 
HP DevOps Summit 2021
HP DevOps Summit 2021HP DevOps Summit 2021
HP DevOps Summit 2021
 
HP's Dev Ops Summit 2021, Better Together: An Inner Source Journey
HP's Dev Ops Summit 2021, Better Together: An Inner Source JourneyHP's Dev Ops Summit 2021, Better Together: An Inner Source Journey
HP's Dev Ops Summit 2021, Better Together: An Inner Source Journey
 
ChatGPT-and-Generative-AI-Landscape Working of generative ai search
ChatGPT-and-Generative-AI-Landscape Working of generative ai searchChatGPT-and-Generative-AI-Landscape Working of generative ai search
ChatGPT-and-Generative-AI-Landscape Working of generative ai search
 
DocOps: Documentation at the Speed of Agile
DocOps: Documentation at the Speed of AgileDocOps: Documentation at the Speed of Agile
DocOps: Documentation at the Speed of Agile
 
No Silver Bullet - Essence and Accidents of Software Engineering
No Silver Bullet - Essence and Accidents of Software EngineeringNo Silver Bullet - Essence and Accidents of Software Engineering
No Silver Bullet - Essence and Accidents of Software Engineering
 
Gobinath.T Resume - Copy
Gobinath.T Resume - CopyGobinath.T Resume - Copy
Gobinath.T Resume - Copy
 
Writing for the Web, It's Not the Same!
Writing for the Web, It's Not the Same!Writing for the Web, It's Not the Same!
Writing for the Web, It's Not the Same!
 
Model-driven and low-code development for event-based systems | Bobby Calderw...
Model-driven and low-code development for event-based systems | Bobby Calderw...Model-driven and low-code development for event-based systems | Bobby Calderw...
Model-driven and low-code development for event-based systems | Bobby Calderw...
 
01_IT4557.pptx
01_IT4557.pptx01_IT4557.pptx
01_IT4557.pptx
 
Raleigh Kafka Meetup - DDD, ES, and CQRS
Raleigh Kafka Meetup - DDD, ES, and CQRSRaleigh Kafka Meetup - DDD, ES, and CQRS
Raleigh Kafka Meetup - DDD, ES, and CQRS
 
User stories deep dive
User stories deep diveUser stories deep dive
User stories deep dive
 
[API the Docs Paris 2018] Architecting DX
[API the Docs Paris 2018] Architecting DX[API the Docs Paris 2018] Architecting DX
[API the Docs Paris 2018] Architecting DX
 

More from 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 Configurations
Pronovix
 
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
Pronovix
 

More from 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
 
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...
 
APIs: Semi-permeable, osmotic interfaces
APIs: Semi-permeable, osmotic interfacesAPIs: Semi-permeable, osmotic interfaces
APIs: Semi-permeable, osmotic interfaces
 

Recently uploaded

Breaking Down the Flutterwave Scandal What You Need to Know.pdf
Breaking Down the Flutterwave Scandal What You Need to Know.pdfBreaking Down the Flutterwave Scandal What You Need to Know.pdf
Breaking Down the Flutterwave Scandal What You Need to Know.pdf
UK Journal
 
Future Visions: Predictions to Guide and Time Tech Innovation, Peter Udo Diehl
Future Visions: Predictions to Guide and Time Tech Innovation, Peter Udo DiehlFuture Visions: Predictions to Guide and Time Tech Innovation, Peter Udo Diehl
Future Visions: Predictions to Guide and Time Tech Innovation, Peter Udo Diehl
Peter Udo Diehl
 

Recently uploaded (20)

AI presentation and introduction - Retrieval Augmented Generation RAG 101
AI presentation and introduction - Retrieval Augmented Generation RAG 101AI presentation and introduction - Retrieval Augmented Generation RAG 101
AI presentation and introduction - Retrieval Augmented Generation RAG 101
 
Portal Kombat : extension du réseau de propagande russe
Portal Kombat : extension du réseau de propagande russePortal Kombat : extension du réseau de propagande russe
Portal Kombat : extension du réseau de propagande russe
 
Optimizing NoSQL Performance Through Observability
Optimizing NoSQL Performance Through ObservabilityOptimizing NoSQL Performance Through Observability
Optimizing NoSQL Performance Through Observability
 
Breaking Down the Flutterwave Scandal What You Need to Know.pdf
Breaking Down the Flutterwave Scandal What You Need to Know.pdfBreaking Down the Flutterwave Scandal What You Need to Know.pdf
Breaking Down the Flutterwave Scandal What You Need to Know.pdf
 
IESVE for Early Stage Design and Planning
IESVE for Early Stage Design and PlanningIESVE for Early Stage Design and Planning
IESVE for Early Stage Design and Planning
 
Demystifying gRPC in .Net by John Staveley
Demystifying gRPC in .Net by John StaveleyDemystifying gRPC in .Net by John Staveley
Demystifying gRPC in .Net by John Staveley
 
Behind the Scenes From the Manager's Chair: Decoding the Secrets of Successfu...
Behind the Scenes From the Manager's Chair: Decoding the Secrets of Successfu...Behind the Scenes From the Manager's Chair: Decoding the Secrets of Successfu...
Behind the Scenes From the Manager's Chair: Decoding the Secrets of Successfu...
 
Overview of Hyperledger Foundation
Overview of Hyperledger FoundationOverview of Hyperledger Foundation
Overview of Hyperledger Foundation
 
AI revolution and Salesforce, Jiří Karpíšek
AI revolution and Salesforce, Jiří KarpíšekAI revolution and Salesforce, Jiří Karpíšek
AI revolution and Salesforce, Jiří Karpíšek
 
Google I/O Extended 2024 Warsaw
Google I/O Extended 2024 WarsawGoogle I/O Extended 2024 Warsaw
Google I/O Extended 2024 Warsaw
 
Unpacking Value Delivery - Agile Oxford Meetup - May 2024.pptx
Unpacking Value Delivery - Agile Oxford Meetup - May 2024.pptxUnpacking Value Delivery - Agile Oxford Meetup - May 2024.pptx
Unpacking Value Delivery - Agile Oxford Meetup - May 2024.pptx
 
Future Visions: Predictions to Guide and Time Tech Innovation, Peter Udo Diehl
Future Visions: Predictions to Guide and Time Tech Innovation, Peter Udo DiehlFuture Visions: Predictions to Guide and Time Tech Innovation, Peter Udo Diehl
Future Visions: Predictions to Guide and Time Tech Innovation, Peter Udo Diehl
 
How Red Hat Uses FDO in Device Lifecycle _ Costin and Vitaliy at Red Hat.pdf
How Red Hat Uses FDO in Device Lifecycle _ Costin and Vitaliy at Red Hat.pdfHow Red Hat Uses FDO in Device Lifecycle _ Costin and Vitaliy at Red Hat.pdf
How Red Hat Uses FDO in Device Lifecycle _ Costin and Vitaliy at Red Hat.pdf
 
Oauth 2.0 Introduction and Flows with MuleSoft
Oauth 2.0 Introduction and Flows with MuleSoftOauth 2.0 Introduction and Flows with MuleSoft
Oauth 2.0 Introduction and Flows with MuleSoft
 
Choosing the Right FDO Deployment Model for Your Application _ Geoffrey at In...
Choosing the Right FDO Deployment Model for Your Application _ Geoffrey at In...Choosing the Right FDO Deployment Model for Your Application _ Geoffrey at In...
Choosing the Right FDO Deployment Model for Your Application _ Geoffrey at In...
 
FDO for Camera, Sensor and Networking Device – Commercial Solutions from VinC...
FDO for Camera, Sensor and Networking Device – Commercial Solutions from VinC...FDO for Camera, Sensor and Networking Device – Commercial Solutions from VinC...
FDO for Camera, Sensor and Networking Device – Commercial Solutions from VinC...
 
ASRock Industrial FDO Solutions in Action for Industrial Edge AI _ Kenny at A...
ASRock Industrial FDO Solutions in Action for Industrial Edge AI _ Kenny at A...ASRock Industrial FDO Solutions in Action for Industrial Edge AI _ Kenny at A...
ASRock Industrial FDO Solutions in Action for Industrial Edge AI _ Kenny at A...
 
Free and Effective: Making Flows Publicly Accessible, Yumi Ibrahimzade
Free and Effective: Making Flows Publicly Accessible, Yumi IbrahimzadeFree and Effective: Making Flows Publicly Accessible, Yumi Ibrahimzade
Free and Effective: Making Flows Publicly Accessible, Yumi Ibrahimzade
 
WebAssembly is Key to Better LLM Performance
WebAssembly is Key to Better LLM PerformanceWebAssembly is Key to Better LLM Performance
WebAssembly is Key to Better LLM Performance
 
PLAI - Acceleration Program for Generative A.I. Startups
PLAI - Acceleration Program for Generative A.I. StartupsPLAI - Acceleration Program for Generative A.I. Startups
PLAI - Acceleration Program for Generative A.I. Startups
 

Creating API documentation for international communities

  • 1. API Documentation for Diverse Communities Alec Clews API The Docs Oct 2022
  • 2. I am speaking to you from the lands of the Wurundjeri people of the Kulin Nation and I wish to acknowledge them as Traditional Owners. I would also like to pay my respects to their Elders, past and present. + More information on Acknowledgement To Country here Acknowledgement of country
  • 3. ► Old school software nerd ► Works as a developer relations advocate at PaperCut Software ► Loves technology and coffee @alecthegeek alecthegeek alecthegeek https://www.linkedin.com/in/alecclews/ ► Pronouns: He/Him Who is Alec?
  • 4. Why is API Docs Accessibility Important? Poorly understood API docs Increase support costs Cultural and individual characteristics affect UNDERSTANDING and Reduce the number of people using your API
  • 5. We can fix this problem It’s Easy! Write Docs with: 1. Intention 2. Empathy
  • 7. Culture has dimensions Importantly ► Societal ► The individual ► Organisational
  • 8. Cultural "Markers" ► The primary Written and Spoken language ► "shared patterns of behaviors and interactions, cognitive constructs, and affective understanding.." Center for Advanced Research on Language Acquisition, University of Minnesota
  • 9. Cultural "Markers" in Software Dev Teams ► Product development approach (processes & maturity) ► Relationship with customers ► Domain of business expertise ► Technology choices
  • 10. NOT JUST REFERENCE MATERIAL. For instance What is API documentation? API reference Introductions and Concepts Getting Started guides Task & Story Based Explanations Troubleshooting guides... Technical Writing Here! Sample Code
  • 12. Use Existing Best Practices Write Accessible Content “Accessible writing is good writing. It makes your content easier for everyone to consume.” – Blackboard Write for Global Audiences. See: ► Google developer documentation style guide ► Microsoft Writing Style Guide ► IBM Style Guide ch 8 ► Apple Style Guide https://illlustrations.co/
  • 13. Write Supplementary Material ► Your technology choices may be unfamiliar to many ► Provide additional material in blogs and knowledge bases ► Stops cluttering up API docs with details ► Get additional value from content ● This is one of our most popular posts ⇒
  • 15. Use More Diagrams "One Picture is Worth a Thousand Words" "One Diagram Illuminates 500 Words" Useful for: ► System Components, their Relationships & Deployment ► Sequences of events and API calls ► Workflows & processes ... ► Diagrams are the ALT tag for to SUPPORT the text ► Still provide complete explanations ● & proper ALT tags on all images ► See Docs for Developers An Engineer’s Field Guide to Technical Writing Ch 6
  • 16. Example: Application Programming Interface ► Contract between two pieces of software a.k.a specification. Provides information about: ● What can the clients request (1)? ● What will the server do? ● What will the server send back (2)? ● What can go wrong (3)?
  • 17. Other Media E.g. Videos, images, animated GIFs Use carefully! Issues ► Accessibility ► Harder to keep updated ► Hard to translate But … Sometimes best because: ► Video can illustrate complex procedures ► An image highlights pertinent information
  • 18. Translation ► It's hard to translate technical docs: ● They change frequently ● Manual translation takes time and is expensive ► Controlled natural languages can make translation easier ► Machine Translation may not be good enough ► Your readers will probably paste your content into Google Translate anyway.
  • 20. API Reference Docs via Spec files ► Network API docs can also be generated from specification files ► Examples ● RESTful — Open API Specification (a.k.a. Swagger) ● gRPC — Protocol Buffers ● GraphQL — schema files ● XML-RPC — Write it by hand
  • 21. API Reference Docs via source code ► Can be generated directly from source code comments and declarations ► Utility varies -- need to work within tool constraints ► Examples ● Go -- Godoc ● Java -- Javadoc ● Python -- Docstrings ● .NET C# -- XML documentation comments
  • 22. API Reference Docs Apply your API Style Guide to reference docs as well ► Names (functions, parameters and types) ► Consistent use of terms, explanations ► Simple clear descriptions and summaries
  • 23. Inline Code “Snippets” ► Show individual API calls and responses ► Like diagrams, they support the text ► Important ► But often overused ● No Context ● Syntax, but no semantics
  • 24. Provide Complete, Working, Code Solutions Show me! Don't tell me! ► A concrete way to answer questions ► Builds confidence with quickstart Beware: Dev language is a cultural choice Don't expect your audience to download and run it without prompting Include: ► Exception handling ► Complex API requests and corresponding responses ► API set up and tear down as needed ► Well written code comments
  • 25. Connecting with Your Development Partners
  • 26. "Modern Agile" API Doc Delivery ► Delivered online ► Frequent and rapid updates ► Continuous iteration and improvement ► Engaged Online Communities ► Pull vs Push
  • 27. Other dev teams have different needs ► Stability ► Clear signals ► Regular release cadence ► Formal delivery of assets (e.g. PDF) ► Passive consumption vs active engagement Try and meet people half way
  • 28. Differences in Communication Style ► Some cultures prefer person to person relationship ► Development teams (and others) are not familiar with support desk software and processes ► Fear of being misunderstood may result in long follow up PDF attachments (which can be hard to use and respond to) ► Public forums (e.g. Google groups) may be blocked
  • 29. Top Tip PDF Distribution Tool https://qrdoc.io/ QR Doc is a free service from PaperCut Software that allows you distribute PDF documents and keep them up to date
  • 31. Additional Resources ► Accessible content Google developer documentation style guide ► Make text content readable and understandable W3 Web Content Accessibility Guidelines (WCAG) ► Mozilla Developer network notes on WCAG ► 5 Tips To Improve Technical Writing For An International Audience on LiNUX.COM
  • 32. Resources contd: ► Translation, Localization, and Globalization from the Technical Communication Body of Knowledge ► Testing your Documentation ► Controlled Natural Language Special Interest Group ► Easy English ► User-Friendly Documentations With Simplified Technical English from Help Authoring Soft