THINGS I WISH PEOPLE TOLD ME ABOUT WRITING DOCS @taylor_atx
A presentation at API Strategy & Practice in November 2017 in Portland, OR, USA by Taylor Barnett
THINGS I WISH PEOPLE TOLD ME ABOUT WRITING DOCS @taylor_atx
TAYLOR BARNETT Community Engineer at Keen IO taylor@keen.io @taylor_atx
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 informationcarrying words • Variations in typeface (text size, links, bold, etc) @taylor_atx
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
USABILITY VARIES: PARAGRAPH VS BULLETS @taylor_atx
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
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
USERS ACTUALLY READ CODE SNIPPETS @taylor_atx
WHAT IS THIS CODE SNIPPET MISSING? 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); @taylor_atx
WHAT IS THIS CODE SNIPPET MISSING? 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” } } • First, how do I even run this? ” client.addEvent(“ticket_purchases”, ticketPurchase); @taylor_atx
WHAT IS THIS CODE SNIPPET MISSING? 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” } } • First, how do I even run this? ” • “ReferenceError: Keen is not defined” client.addEvent(“ticket_purchases”, ticketPurchase); @taylor_atx
WHAT IS THIS CODE SNIPPET MISSING? 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” } } • First, how do I even run this? ” • “ReferenceError: Keen is not defined” • Didn’t set the Project ID and Write Key client.addEvent(“ticket_purchases”, ticketPurchase); @taylor_atx
PREVENT COPY AND PASTE BUGS What will this return?
🤔 $ gem install rails @taylor_atx
PREVENT COPY AND PASTE BUGS What will this return?
😔 @taylor_atx
TWILIO @taylor_atx
WHAT DO I MEAN BY “DOCS?” API REFERENCES GUIDES TUTORIALS BLOG POSTS* @taylor_atx
GUIDES • Somewhere between API references and tutorials • Similar reference but with prose that explains how to use the API • Example: Authorization guide @taylor_atx
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
SPRING FRAMEWORK @taylor_atx
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
@taylor_atx
DOCS NAVIGATION AND UNIVERSAL PRINCIPLES OF DESIGN @taylor_atx
DOCS PORTAL HOMEPAGE PRODUCT HOMEPAGE SECTION HOMEPAGE PAGE @taylor_atx
@taylor_atx
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
@taylor_atx
@taylor_atx
😨 😨 @taylor_atx
LIBRARIES SDKS WRAPPERS CLIENTS @taylor_atx
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
EMPATHY FAILURE BEGINNER’S MIND FAILURE @taylor_atx
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
@taylor_atx
ERROR MESSAGES @taylor_atx
ERROR MESSAGES ARE AN OPPORTUNITY @taylor_atx
3 H’S OF GOOD ERROR MESSAGES: HUMBLE HUMAN HELPFUL @taylor_atx
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
HUMAN • Speak in human terms • Example: • Your API Key is invalid, please try a different key. @taylor_atx
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
WRITING ERROR MESSAGES 1. Acknowledge 2. Apologize 3. Explain 4. Help @taylor_atx
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
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
HOW DO I GET OTHER TEAMMATES TO CONTRIBUTE TO DOCS? @taylor_atx
“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
MAKE SURE CONTRIBUTORS ARE VALUED & REWARDED @taylor_atx
SHOW THE BENEFITS @taylor_atx
GITHUB FOR DOCS • Continuous integration and automated testing • Issues • Incremental changes @taylor_atx
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
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
TAYLOR BARNETT Community Engineer at Keen IO taylor@keen.io @taylor_atx
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-apidocs/ • 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/breakingdown-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-writedocumentation.html • Docs like Code book: https://www.docslikecode.com/
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
