SlideShare a Scribd company logo

Things I Wish People Told Me About Writing Docs

APIStrat 2017 Have you ever read a piece of API documentation and thought it was a mess? Maybe it was incomplete, badly organized, or in general just not great. There’s a good chance it was quickly thrown together by someone who had no idea what they were doing. In this talk, we will discuss the things Taylor wished she knew before starting to dive into the world of writing docs and developer focused content. We will discuss how people actually read documentation, different types of docs and when they are appropriate, and docs navigation techniques using design principles. Also, we will learn more about the importance of focusing on language, including why naming matters and error messages as a form of documentation. Lastly, we will talk about tools and tactics to enable other team members to write documentation.

1 of 63
Download to read offline
THINGS I WISH PEOPLE TOLD
ME ABOUT WRITING DOCS
@taylor_atx
Community Engineer at Keen IO
taylor@keen.io
@taylor_atx
TAYLOR BARNETT
HOW DO PEOPLE
ACTUALLY READ DOCS?
@taylor_atx
@taylor_atx
https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content
IMPLICATIONS OF F SHAPE
• First two paragraphs must state the most important
information
• Further, the first 3-5 words are very important
• Start headers, paragraphs, and bullet points with information-
carrying words
• Variations in typeface (text size, links, bold, etc)
@taylor_atx

Recommended

Unless It Was a Digital Dog, No One Ate Your Homework (Diigo)
Unless It Was a Digital Dog, No One Ate Your Homework (Diigo)Unless It Was a Digital Dog, No One Ate Your Homework (Diigo)
Unless It Was a Digital Dog, No One Ate Your Homework (Diigo)Lisa Sjogren
 
Owl and The Hummingbird - Ontology and SEO
Owl and The Hummingbird - Ontology and SEOOwl and The Hummingbird - Ontology and SEO
Owl and The Hummingbird - Ontology and SEODawn Anderson MSc DigM
 
Visualizing your Graph
Visualizing your GraphVisualizing your Graph
Visualizing your GraphMax De Marzi
 
Making Your Site Printable: CSS Summit 2014
Making Your Site Printable: CSS Summit 2014Making Your Site Printable: CSS Summit 2014
Making Your Site Printable: CSS Summit 2014Adrian Roselli
 
Neo4j Training Introduction
Neo4j Training IntroductionNeo4j Training Introduction
Neo4j Training IntroductionMax De Marzi
 
Selfish Accessibility: HTML5 Developer Conference 2014
Selfish Accessibility: HTML5 Developer Conference 2014Selfish Accessibility: HTML5 Developer Conference 2014
Selfish Accessibility: HTML5 Developer Conference 2014Adrian Roselli
 
Selfish Accessibility: WordCamp Buffalo 2014
Selfish Accessibility: WordCamp Buffalo 2014Selfish Accessibility: WordCamp Buffalo 2014
Selfish Accessibility: WordCamp Buffalo 2014Adrian Roselli
 

More Related Content

What's hot

Selfish Accessibility — WordCamp Europe 2017
Selfish Accessibility — WordCamp Europe 2017Selfish Accessibility — WordCamp Europe 2017
Selfish Accessibility — WordCamp Europe 2017Adrian Roselli
 
Week 6 - Interactive News Editing and Producing
Week 6 - Interactive News Editing and ProducingWeek 6 - Interactive News Editing and Producing
Week 6 - Interactive News Editing and Producingkurtgessler
 
SearchCon 2016 | Black Hat Tools for White Hat SEO with Jim Kreinbrink, Cade ...
SearchCon 2016 | Black Hat Tools for White Hat SEO with Jim Kreinbrink, Cade ...SearchCon 2016 | Black Hat Tools for White Hat SEO with Jim Kreinbrink, Cade ...
SearchCon 2016 | Black Hat Tools for White Hat SEO with Jim Kreinbrink, Cade ...SearchCon
 
ONA08 - Jesse Thomas
ONA08 - Jesse ThomasONA08 - Jesse Thomas
ONA08 - Jesse ThomasJesse Thomas
 
Selfish Accessibility: MinneWebCon 2017
Selfish Accessibility: MinneWebCon 2017Selfish Accessibility: MinneWebCon 2017
Selfish Accessibility: MinneWebCon 2017Adrian Roselli
 

What's hot (6)

Selfish Accessibility — WordCamp Europe 2017
Selfish Accessibility — WordCamp Europe 2017Selfish Accessibility — WordCamp Europe 2017
Selfish Accessibility — WordCamp Europe 2017
 
Week 6 - Interactive News Editing and Producing
Week 6 - Interactive News Editing and ProducingWeek 6 - Interactive News Editing and Producing
Week 6 - Interactive News Editing and Producing
 
Websites 201
Websites 201Websites 201
Websites 201
 
SearchCon 2016 | Black Hat Tools for White Hat SEO with Jim Kreinbrink, Cade ...
SearchCon 2016 | Black Hat Tools for White Hat SEO with Jim Kreinbrink, Cade ...SearchCon 2016 | Black Hat Tools for White Hat SEO with Jim Kreinbrink, Cade ...
SearchCon 2016 | Black Hat Tools for White Hat SEO with Jim Kreinbrink, Cade ...
 
ONA08 - Jesse Thomas
ONA08 - Jesse ThomasONA08 - Jesse Thomas
ONA08 - Jesse Thomas
 
Selfish Accessibility: MinneWebCon 2017
Selfish Accessibility: MinneWebCon 2017Selfish Accessibility: MinneWebCon 2017
Selfish Accessibility: MinneWebCon 2017
 

Similar to Things I Wish People Told Me About Writing Docs

Explode conftalk - v2 ppt
Explode conftalk  - v2 pptExplode conftalk  - v2 ppt
Explode conftalk - v2 pptEmily Wyss
 
How to Use Social Media for Recruiting
How to Use Social Media for RecruitingHow to Use Social Media for Recruiting
How to Use Social Media for RecruitingClaravon Group
 
Article Writing Tips
Article Writing TipsArticle Writing Tips
Article Writing TipsMd Ekram
 
Wordcamp St. Louis - Clean Coding
Wordcamp St. Louis - Clean CodingWordcamp St. Louis - Clean Coding
Wordcamp St. Louis - Clean Codinginspector_fegter
 
"How do I Architect?" - Quick Introduction to Architecture for Salesforce Ad...
"How do I Architect?"  - Quick Introduction to Architecture for Salesforce Ad..."How do I Architect?"  - Quick Introduction to Architecture for Salesforce Ad...
"How do I Architect?" - Quick Introduction to Architecture for Salesforce Ad...Steven Herod
 
Code Reviews @ Quatico
Code Reviews @ QuaticoCode Reviews @ Quatico
Code Reviews @ QuaticoJan Wloka
 
Site Crawling: What To Do & What To Look For
Site Crawling: What To Do & What To Look ForSite Crawling: What To Do & What To Look For
Site Crawling: What To Do & What To Look ForOutspoken Media
 
Creating a Great Developer Experience Through SDKs
Creating a Great Developer Experience Through SDKsCreating a Great Developer Experience Through SDKs
Creating a Great Developer Experience Through SDKsTaylor Barnett
 
Agile Toronto 2018 - Sharpen Your Agile Ax ... Story Splitting Time
Agile Toronto 2018 - Sharpen Your Agile Ax ... Story Splitting TimeAgile Toronto 2018 - Sharpen Your Agile Ax ... Story Splitting Time
Agile Toronto 2018 - Sharpen Your Agile Ax ... Story Splitting TimeBrian Sjoberg
 
Content Structure Workshop - Content Marketing World 2019
Content Structure Workshop - Content Marketing World 2019Content Structure Workshop - Content Marketing World 2019
Content Structure Workshop - Content Marketing World 2019Laura Creekmore
 
2015 rubyconf - 百大媒體網站從 Wordpress 到 Rails 的大小事
2015 rubyconf - 百大媒體網站從 Wordpress 到 Rails 的大小事2015 rubyconf - 百大媒體網站從 Wordpress 到 Rails 的大小事
2015 rubyconf - 百大媒體網站從 Wordpress 到 Rails 的大小事Ronald Hsu
 
WordPress 4.4 and Beyond
WordPress 4.4 and BeyondWordPress 4.4 and Beyond
WordPress 4.4 and BeyondScott Taylor
 
Content design for communicators and publishers- IntraTeam 2020
Content design for communicators and publishers- IntraTeam 2020Content design for communicators and publishers- IntraTeam 2020
Content design for communicators and publishers- IntraTeam 2020Intranet Now
 
A crash course into SEO and what moves the needle with scalable processes
A crash course into SEO and what moves the needle with scalable processesA crash course into SEO and what moves the needle with scalable processes
A crash course into SEO and what moves the needle with scalable processespatrickstox
 
Content Publishing
Content PublishingContent Publishing
Content PublishingAutodesk
 
Writing code for others
Writing code for othersWriting code for others
Writing code for othersAmol Pujari
 
Lavacon preso-2015-miranda-meyers
Lavacon preso-2015-miranda-meyersLavacon preso-2015-miranda-meyers
Lavacon preso-2015-miranda-meyersJoe Meyers
 
GDD Moscow - Open Social
GDD Moscow - Open SocialGDD Moscow - Open Social
GDD Moscow - Open SocialChris Chabot
 
Creating More Engaging Content For Social
Creating More Engaging Content For SocialCreating More Engaging Content For Social
Creating More Engaging Content For SocialEric T. Tung
 
Life cycle of user story: Outside-in agile product management & testing, or...
Life cycle of user story: Outside-in agile product management & testing, or...Life cycle of user story: Outside-in agile product management & testing, or...
Life cycle of user story: Outside-in agile product management & testing, or...Ravi Tadwalkar
 

Similar to Things I Wish People Told Me About Writing Docs (20)

Explode conftalk - v2 ppt
Explode conftalk  - v2 pptExplode conftalk  - v2 ppt
Explode conftalk - v2 ppt
 
How to Use Social Media for Recruiting
How to Use Social Media for RecruitingHow to Use Social Media for Recruiting
How to Use Social Media for Recruiting
 
Article Writing Tips
Article Writing TipsArticle Writing Tips
Article Writing Tips
 
Wordcamp St. Louis - Clean Coding
Wordcamp St. Louis - Clean CodingWordcamp St. Louis - Clean Coding
Wordcamp St. Louis - Clean Coding
 
"How do I Architect?" - Quick Introduction to Architecture for Salesforce Ad...
"How do I Architect?"  - Quick Introduction to Architecture for Salesforce Ad..."How do I Architect?"  - Quick Introduction to Architecture for Salesforce Ad...
"How do I Architect?" - Quick Introduction to Architecture for Salesforce Ad...
 
Code Reviews @ Quatico
Code Reviews @ QuaticoCode Reviews @ Quatico
Code Reviews @ Quatico
 
Site Crawling: What To Do & What To Look For
Site Crawling: What To Do & What To Look ForSite Crawling: What To Do & What To Look For
Site Crawling: What To Do & What To Look For
 
Creating a Great Developer Experience Through SDKs
Creating a Great Developer Experience Through SDKsCreating a Great Developer Experience Through SDKs
Creating a Great Developer Experience Through SDKs
 
Agile Toronto 2018 - Sharpen Your Agile Ax ... Story Splitting Time
Agile Toronto 2018 - Sharpen Your Agile Ax ... Story Splitting TimeAgile Toronto 2018 - Sharpen Your Agile Ax ... Story Splitting Time
Agile Toronto 2018 - Sharpen Your Agile Ax ... Story Splitting Time
 
Content Structure Workshop - Content Marketing World 2019
Content Structure Workshop - Content Marketing World 2019Content Structure Workshop - Content Marketing World 2019
Content Structure Workshop - Content Marketing World 2019
 
2015 rubyconf - 百大媒體網站從 Wordpress 到 Rails 的大小事
2015 rubyconf - 百大媒體網站從 Wordpress 到 Rails 的大小事2015 rubyconf - 百大媒體網站從 Wordpress 到 Rails 的大小事
2015 rubyconf - 百大媒體網站從 Wordpress 到 Rails 的大小事
 
WordPress 4.4 and Beyond
WordPress 4.4 and BeyondWordPress 4.4 and Beyond
WordPress 4.4 and Beyond
 
Content design for communicators and publishers- IntraTeam 2020
Content design for communicators and publishers- IntraTeam 2020Content design for communicators and publishers- IntraTeam 2020
Content design for communicators and publishers- IntraTeam 2020
 
A crash course into SEO and what moves the needle with scalable processes
A crash course into SEO and what moves the needle with scalable processesA crash course into SEO and what moves the needle with scalable processes
A crash course into SEO and what moves the needle with scalable processes
 
Content Publishing
Content PublishingContent Publishing
Content Publishing
 
Writing code for others
Writing code for othersWriting code for others
Writing code for others
 
Lavacon preso-2015-miranda-meyers
Lavacon preso-2015-miranda-meyersLavacon preso-2015-miranda-meyers
Lavacon preso-2015-miranda-meyers
 
GDD Moscow - Open Social
GDD Moscow - Open SocialGDD Moscow - Open Social
GDD Moscow - Open Social
 
Creating More Engaging Content For Social
Creating More Engaging Content For SocialCreating More Engaging Content For Social
Creating More Engaging Content For Social
 
Life cycle of user story: Outside-in agile product management & testing, or...
Life cycle of user story: Outside-in agile product management & testing, or...Life cycle of user story: Outside-in agile product management & testing, or...
Life cycle of user story: Outside-in agile product management & testing, or...
 

Recently uploaded

Energy Efficient Social Housing for One Manchester
Energy Efficient Social Housing for One ManchesterEnergy Efficient Social Housing for One Manchester
Energy Efficient Social Housing for One Manchestermark alegbe
 
Paper Machine Troubleshooting manual for paper makers
Paper Machine Troubleshooting manual for paper makersPaper Machine Troubleshooting manual for paper makers
Paper Machine Troubleshooting manual for paper makersNoman khan
 
python presentation lists,strings,operation
python presentation lists,strings,operationpython presentation lists,strings,operation
python presentation lists,strings,operationManjuRaghavan1
 
21 SCHEME_21EC53_VTU_MODULE-4_COMPUTER COMMUNCATION NETWORK.pdf
21 SCHEME_21EC53_VTU_MODULE-4_COMPUTER COMMUNCATION NETWORK.pdf21 SCHEME_21EC53_VTU_MODULE-4_COMPUTER COMMUNCATION NETWORK.pdf
21 SCHEME_21EC53_VTU_MODULE-4_COMPUTER COMMUNCATION NETWORK.pdfDr. Shivashankar
 
POST HARVEST Threshing equipment PPT 2.pptx
POST HARVEST Threshing equipment PPT 2.pptxPOST HARVEST Threshing equipment PPT 2.pptx
POST HARVEST Threshing equipment PPT 2.pptxARUL S
 
Microstructure of Hadfield Steels (Robert Hadfield)
Microstructure of Hadfield Steels (Robert Hadfield)Microstructure of Hadfield Steels (Robert Hadfield)
Microstructure of Hadfield Steels (Robert Hadfield)MANICKAVASAHAM G
 
PM24_Oral_Presentation_Template_Guidelines.pptx
PM24_Oral_Presentation_Template_Guidelines.pptxPM24_Oral_Presentation_Template_Guidelines.pptx
PM24_Oral_Presentation_Template_Guidelines.pptxnissamant
 
FSMR - FIRE SAFETY MAINTENANCE REPORT FORM.pdf
FSMR - FIRE SAFETY MAINTENANCE REPORT FORM.pdfFSMR - FIRE SAFETY MAINTENANCE REPORT FORM.pdf
FSMR - FIRE SAFETY MAINTENANCE REPORT FORM.pdfArnold Saludares
 
Introduction to the telecom tower industry
Introduction to the telecom tower industryIntroduction to the telecom tower industry
Introduction to the telecom tower industryssuserf5bbfd
 
fat and edible oil processsing.ppt, refining
fat and edible oil processsing.ppt, refiningfat and edible oil processsing.ppt, refining
fat and edible oil processsing.ppt, refiningteddymebratie
 
Checklist to troubleshoot CD moisture profiles.docx
Checklist to troubleshoot CD moisture profiles.docxChecklist to troubleshoot CD moisture profiles.docx
Checklist to troubleshoot CD moisture profiles.docxNoman khan
 
Amplitude modulation and Demodulation Techniques
Amplitude modulation and Demodulation TechniquesAmplitude modulation and Demodulation Techniques
Amplitude modulation and Demodulation TechniquesRich171473
 
Introduction to Machine Learning Unit-1 Notes for II-II Mechanical Engineerin...
Introduction to Machine Learning Unit-1 Notes for II-II Mechanical Engineerin...Introduction to Machine Learning Unit-1 Notes for II-II Mechanical Engineerin...
Introduction to Machine Learning Unit-1 Notes for II-II Mechanical Engineerin...C Sai Kiran
 
Integrity Constraints in Database Management System.pptx
Integrity Constraints in Database Management System.pptxIntegrity Constraints in Database Management System.pptx
Integrity Constraints in Database Management System.pptxPallaviPatil905338
 
Model Approved Food/ sanitary Grade Flow Meter
Model Approved Food/ sanitary Grade Flow MeterModel Approved Food/ sanitary Grade Flow Meter
Model Approved Food/ sanitary Grade Flow MeterManasMicrosystems
 
Microservices: Benefits, drawbacks and are they for me?
Microservices: Benefits, drawbacks and are they for me?Microservices: Benefits, drawbacks and are they for me?
Microservices: Benefits, drawbacks and are they for me?Marian Marinov
 
Basic Instrumentation Symbols | P&ID | PFD | Gaurav Singh Rajput
Basic Instrumentation Symbols | P&ID | PFD | Gaurav Singh RajputBasic Instrumentation Symbols | P&ID | PFD | Gaurav Singh Rajput
Basic Instrumentation Symbols | P&ID | PFD | Gaurav Singh RajputGaurav Singh Rajput
 
【文凭定制】坎特伯雷大学毕业证学历认证
【文凭定制】坎特伯雷大学毕业证学历认证【文凭定制】坎特伯雷大学毕业证学历认证
【文凭定制】坎特伯雷大学毕业证学历认证muvgemo
 

Recently uploaded (20)

Energy Efficient Social Housing for One Manchester
Energy Efficient Social Housing for One ManchesterEnergy Efficient Social Housing for One Manchester
Energy Efficient Social Housing for One Manchester
 
Paper Machine Troubleshooting manual for paper makers
Paper Machine Troubleshooting manual for paper makersPaper Machine Troubleshooting manual for paper makers
Paper Machine Troubleshooting manual for paper makers
 
python presentation lists,strings,operation
python presentation lists,strings,operationpython presentation lists,strings,operation
python presentation lists,strings,operation
 
21 SCHEME_21EC53_VTU_MODULE-4_COMPUTER COMMUNCATION NETWORK.pdf
21 SCHEME_21EC53_VTU_MODULE-4_COMPUTER COMMUNCATION NETWORK.pdf21 SCHEME_21EC53_VTU_MODULE-4_COMPUTER COMMUNCATION NETWORK.pdf
21 SCHEME_21EC53_VTU_MODULE-4_COMPUTER COMMUNCATION NETWORK.pdf
 
POST HARVEST Threshing equipment PPT 2.pptx
POST HARVEST Threshing equipment PPT 2.pptxPOST HARVEST Threshing equipment PPT 2.pptx
POST HARVEST Threshing equipment PPT 2.pptx
 
Microstructure of Hadfield Steels (Robert Hadfield)
Microstructure of Hadfield Steels (Robert Hadfield)Microstructure of Hadfield Steels (Robert Hadfield)
Microstructure of Hadfield Steels (Robert Hadfield)
 
PM24_Oral_Presentation_Template_Guidelines.pptx
PM24_Oral_Presentation_Template_Guidelines.pptxPM24_Oral_Presentation_Template_Guidelines.pptx
PM24_Oral_Presentation_Template_Guidelines.pptx
 
FSMR - FIRE SAFETY MAINTENANCE REPORT FORM.pdf
FSMR - FIRE SAFETY MAINTENANCE REPORT FORM.pdfFSMR - FIRE SAFETY MAINTENANCE REPORT FORM.pdf
FSMR - FIRE SAFETY MAINTENANCE REPORT FORM.pdf
 
Introduction to the telecom tower industry
Introduction to the telecom tower industryIntroduction to the telecom tower industry
Introduction to the telecom tower industry
 
fat and edible oil processsing.ppt, refining
fat and edible oil processsing.ppt, refiningfat and edible oil processsing.ppt, refining
fat and edible oil processsing.ppt, refining
 
Checklist to troubleshoot CD moisture profiles.docx
Checklist to troubleshoot CD moisture profiles.docxChecklist to troubleshoot CD moisture profiles.docx
Checklist to troubleshoot CD moisture profiles.docx
 
Amplitude modulation and Demodulation Techniques
Amplitude modulation and Demodulation TechniquesAmplitude modulation and Demodulation Techniques
Amplitude modulation and Demodulation Techniques
 
Introduction to Machine Learning Unit-1 Notes for II-II Mechanical Engineerin...
Introduction to Machine Learning Unit-1 Notes for II-II Mechanical Engineerin...Introduction to Machine Learning Unit-1 Notes for II-II Mechanical Engineerin...
Introduction to Machine Learning Unit-1 Notes for II-II Mechanical Engineerin...
 
AC DISTRIBUTION - ELECTRICAL POWER SYSTEM
AC DISTRIBUTION - ELECTRICAL POWER SYSTEMAC DISTRIBUTION - ELECTRICAL POWER SYSTEM
AC DISTRIBUTION - ELECTRICAL POWER SYSTEM
 
Présentation IIRB 2024 Corentin Sochard - ÌTB
Présentation IIRB 2024 Corentin Sochard - ÌTBPrésentation IIRB 2024 Corentin Sochard - ÌTB
Présentation IIRB 2024 Corentin Sochard - ÌTB
 
Integrity Constraints in Database Management System.pptx
Integrity Constraints in Database Management System.pptxIntegrity Constraints in Database Management System.pptx
Integrity Constraints in Database Management System.pptx
 
Model Approved Food/ sanitary Grade Flow Meter
Model Approved Food/ sanitary Grade Flow MeterModel Approved Food/ sanitary Grade Flow Meter
Model Approved Food/ sanitary Grade Flow Meter
 
Microservices: Benefits, drawbacks and are they for me?
Microservices: Benefits, drawbacks and are they for me?Microservices: Benefits, drawbacks and are they for me?
Microservices: Benefits, drawbacks and are they for me?
 
Basic Instrumentation Symbols | P&ID | PFD | Gaurav Singh Rajput
Basic Instrumentation Symbols | P&ID | PFD | Gaurav Singh RajputBasic Instrumentation Symbols | P&ID | PFD | Gaurav Singh Rajput
Basic Instrumentation Symbols | P&ID | PFD | Gaurav Singh Rajput
 
【文凭定制】坎特伯雷大学毕业证学历认证
【文凭定制】坎特伯雷大学毕业证学历认证【文凭定制】坎特伯雷大学毕业证学历认证
【文凭定制】坎特伯雷大学毕业证学历认证
 

Things I Wish People Told Me About Writing Docs

  • 1. THINGS I WISH PEOPLE TOLD ME ABOUT WRITING DOCS @taylor_atx
  • 2. Community Engineer at Keen IO taylor@keen.io @taylor_atx TAYLOR BARNETT
  • 3. HOW DO PEOPLE ACTUALLY READ DOCS? @taylor_atx
  • 6. IMPLICATIONS OF F SHAPE • First two paragraphs must state the most important information • Further, the first 3-5 words are very important • Start headers, paragraphs, and bullet points with information- carrying words • Variations in typeface (text size, links, bold, etc) @taylor_atx
  • 7. STRUCTURE • Prevent search failure - what the users wants doesn’t stand out • One idea per paragraph, if there’s more than one, split the paragraphs • Users skip over things that look like ads • Aim for 65-90 characters in width @taylor_atx
  • 8. USABILITY VARIES: PARAGRAPH VS BULLETS @taylor_atx
  • 9. USABILITY VARIES: PARAGRAPH VS BULLETS Event collections can have almost any name, but there are a few rules to follow: The name must be 64 characters or less. It must contain only Ascii characters. It cannot be a null value.
 @taylor_atx
  • 10. USABILITY VARIES: PARAGRAPH VS BULLETS Event collections can have almost any name, but there are a few rules to follow: The name must be 64 characters or less. It must contain only Ascii characters. It cannot be a null value.
 Event collections can have almost any name, but there are a few rules to follow: • The name must be 64 characters or less. • It must contain only Ascii characters. • It cannot be a null value. @taylor_atx
  • 11. USERS ACTUALLY READ CODE SNIPPETS @taylor_atx
  • 12. var client = new Keen({   projectId: "your_project_id",   writeKey: "your_write_key" }); var ticketPurchase = {   price: 50.00,   user: {     id: "020939382",     age: 28   },   artist: {     id: "19039",     name: "Tycho"   } } client.addEvent("ticket_purchases", ticketPurchase); WHAT IS THIS CODE SNIPPET MISSING? 🤔 @taylor_atx
  • 13. var client = new Keen({   projectId: "your_project_id",   writeKey: "your_write_key" }); var ticketPurchase = {   price: 50.00,   user: {     id: "020939382",     age: 28   },   artist: {     id: "19039",     name: "Tycho"   } } client.addEvent("ticket_purchases", ticketPurchase); WHAT IS THIS CODE SNIPPET MISSING? • First, how do I even run this? " @taylor_atx
  • 14. var client = new Keen({   projectId: "your_project_id",   writeKey: "your_write_key" }); var ticketPurchase = {   price: 50.00,   user: {     id: "020939382",     age: 28   },   artist: {     id: "19039",     name: "Tycho"   } } client.addEvent("ticket_purchases", ticketPurchase); WHAT IS THIS CODE SNIPPET MISSING? • First, how do I even run this? • “ReferenceError: Keen is not defined” " @taylor_atx
  • 15. var client = new Keen({   projectId: "your_project_id",   writeKey: "your_write_key" }); var ticketPurchase = {   price: 50.00,   user: {     id: "020939382",     age: 28   },   artist: {     id: "19039",     name: "Tycho"   } } client.addEvent("ticket_purchases", ticketPurchase); WHAT IS THIS CODE SNIPPET MISSING? • First, how do I even run this? • “ReferenceError: Keen is not defined” • Didn’t set the Project ID and Write Key " @taylor_atx
  • 16. What will this return? # Copy and paste the following command $ gem install rails PREVENT COPY AND PASTE BUGS 🤔 @taylor_atx
  • 17. What will this return? # Copy and paste the following command $ gem install rails PREVENT COPY AND PASTE BUGS 😔 # Returns “bash: command not found: $” @taylor_atx
  • 19. WHAT DO I MEAN BY “DOCS?” API REFERENCES GUIDES TUTORIALS BLOG POSTS* @taylor_atx
  • 20. GUIDES • Somewhere between API references and tutorials • Similar reference but with prose that explains how to use the API • Example: Authorization guide @taylor_atx
  • 22. TUTORIALS • Teach specific things with an API, beginning to end, including setup • Tightly focused on a few pieces of functionality • Includes working sample code • Example: Getting Started or Hello World tutorial @taylor_atx
  • 24. BLOG POSTS • “Share Knowledge, Not Features” — Adam DuVander • Features != Benefits • A blog post should teach, inspire, and help • Give a preview, then help navigate them to the full docs @taylor_atx
  • 26. DOCS NAVIGATION AND UNIVERSAL PRINCIPLES OF DESIGN @taylor_atx
  • 28. 1. NAVIGATE FROM DOC SET TO DOC SET @taylor_atx
  • 29. DOCS PORTAL HOMEPAGE PRODUCT HOMEPAGE SECTION HOMEPAGE PAGE @taylor_atx
  • 32. 2. ALLOW NAVIGATION WITHIN CONTENT @taylor_atx
  • 33. BOTTOM-UP NAVIGATION • If you tell me I can do something, link to how to do that something. • If you tell me I can use something, link to a description of that something. • If you mention a concept or an idea, link to a description of that concept or idea. — Mark Baker from “Every Page is Page One” @taylor_atx
  • 41. WHY DO BAD NAMES PERSIST? • Because we don’t realize that the name is bad • Or we do, but can’t or won’t justify fixing it because we… • Are tied to it • Can’t justify the time • Don’t know the value • Don’t have the agency to fix it @taylor_atx
  • 42. EMPATHY FAILURE BEGINNER’S MIND FAILURE @taylor_atx
  • 43. WORD CHOICE IS HARD • Hard to give one framework to use, but you can… • Talk to users, get feedback - ask someone to review it • Refactor and rewrite • Search existing names @taylor_atx
  • 46. ERROR MESSAGES ARE AN OPPORTUNITY @taylor_atx
  • 47. 3 H’S OF GOOD ERROR MESSAGES: HUMBLE HUMAN HELPFUL @taylor_atx
  • 48. HUMBLE • Apologize even if it is not your fault • Example: • Sorry, we could not connect to ___. Please check your network settings, connect to an available network, and try again. @taylor_atx
  • 49. HUMAN • Speak in human terms • Example: • Your API Key is invalid, please try a different key. @taylor_atx
  • 50. HELPFUL • Share what the users can expect or do to fix the problem • Example: • Sorry, the image you tried to upload is too big. Try again with an image smaller than 4000px tall by 4000px wide. @taylor_atx
  • 51. WRITING ERROR MESSAGES 1. Acknowledge 2. Apologize 3. Explain 4. Help @taylor_atx
  • 52. WRITING ERROR MESSAGES • Object first, action second • What the users wants first, how to get there second • If you can, put the input in the error string @taylor_atx
  • 53. ERROR MESSAGE SEO • If users get an error message often, put the exact text in your docs • You can also edit StackOverflow posts @taylor_atx
  • 54. HOW DO I GET OTHER TEAMMATES TO CONTRIBUTE TO DOCS? @taylor_atx
  • 55. “I DON’T HAVE THE TIME” “DOCS ARE HARD TO MAINTAIN” “JUST READ THE SOURCE” “DOCUMENTATION IS USELESS” — Fred Hebert from “Don't be a Jerk: Write Documentation” @taylor_atx
  • 56. MAKE SURE CONTRIBUTORS ARE VALUED & REWARDED @taylor_atx
  • 58. GITHUB FOR DOCS • Continuous integration and automated testing • Issues • Incremental changes @taylor_atx
  • 59. REVIEWS • “Pair” on reviews • Use reviews to coach contributors • For small suggestions, fix it yourself and share before merging • If a review sounds harsh, reach out and let them know you aim to instruct and appreciate them @taylor_atx
  • 60. STYLE GUIDES • Frees your contributors to focus on what’s more valuable, instead of grammar, consistency, or other issues • Examples: • Google Developer Documentation Style Guide • 18F Content Guide @taylor_atx
  • 61. Community Engineer at Keen IO taylor@keen.io @taylor_atx TAYLOR BARNETT
  • 62. APPENDIX: LINKS • How Users Read on the Web article: https://www.nngroup.com/articles/how-users-read-on-the-web/ • Articles: https://www.nngroup.com/topic/writing-web/ • How to Write Documentation for People that Don't Read talk: https://youtu.be/sQP_hUNCrcE • Designing Great API Docs blog post: http://blog.parse.com/learn/engineering/designing-great-api- docs/ • Blog plus much more: http://idratherbewriting.com/ • Building navigation for your doc site: 5 best practices talk: https://youtu.be/w-kEmsLwPDE • Building navigation for your documentation site: 5 best practices in design blog post: http:// idratherbewriting.com/files/doc-navigation-wtd/design-principles-for-doc-navigation/ • Breaking Down Barriers to “Hello World” talk: https://www.slideshare.net/taylorsoitgoes/breaking- down-barriers-to-hello-world-79181115 • Even Naming This Talk Is Hard talk: https://youtu.be/RFfpkrbkvxc • Error Messages: Being Humble, Human, and Helpful talk: https://youtu.be/gBBZUATL7Qo • Don't be a Jerk: Write Documentation blog post: https://ferd.ca/don-t-be-a-jerk-write- documentation.html • Docs like Code book: https://www.docslikecode.com/
  • 63. APPENDIX: A NOTE ON OPENAPI SPECIFICATION • Spec output can provide a clear source for reference info about endpoints, parameters, requests, and responses • Auto generation is a starting point • Still need more use cases, authorization, why API exists, more samples, and tutorials • Think of it as a compliment, a sandbox to play around with • Two sites isn’t necessarily a bad thing @taylor_atx