Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Things I Wish People Told Me About Writing Docs

1,069 views

Published on

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.

Published in: Engineering

Things I Wish People Told Me About Writing Docs

  1. 1. THINGS I WISH PEOPLE TOLD ME ABOUT WRITING DOCS @taylor_atx
  2. 2. Community Engineer at Keen IO taylor@keen.io @taylor_atx TAYLOR BARNETT
  3. 3. HOW DO PEOPLE ACTUALLY READ DOCS? @taylor_atx
  4. 4. @taylor_atx
  5. 5. https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content
  6. 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. 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. 8. USABILITY VARIES: PARAGRAPH VS BULLETS @taylor_atx
  9. 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. 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. 11. USERS ACTUALLY READ CODE SNIPPETS @taylor_atx
  12. 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. 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. 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. 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. 16. What will this return? # Copy and paste the following command $ gem install rails PREVENT COPY AND PASTE BUGS 🤔 @taylor_atx
  17. 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
  18. 18. TWILIO @taylor_atx
  19. 19. WHAT DO I MEAN BY “DOCS?” API REFERENCES GUIDES TUTORIALS BLOG POSTS* @taylor_atx
  20. 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
  21. 21. 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
  22. 22. SPRING FRAMEWORK @taylor_atx
  23. 23. 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
  24. 24. @taylor_atx
  25. 25. DOCS NAVIGATION AND UNIVERSAL PRINCIPLES OF DESIGN @taylor_atx
  26. 26. 1. PROGRESSIVE DISCLOSURE @taylor_atx
  27. 27. 1. NAVIGATE FROM DOC SET TO DOC SET @taylor_atx
  28. 28. DOCS PORTAL HOMEPAGE PRODUCT HOMEPAGE SECTION HOMEPAGE PAGE @taylor_atx
  29. 29. @taylor_atx
  30. 30. 2. IMMERSION @taylor_atx
  31. 31. 2. ALLOW NAVIGATION WITHIN CONTENT @taylor_atx
  32. 32. 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
  33. 33. @taylor_atx
  34. 34. 3. MODULARITY @taylor_atx
  35. 35. 3. REDUCE INFORMATION FRAGMENTATION @taylor_atx
  36. 36. @taylor_atx
  37. 37. 😨 😨 @taylor_atx
  38. 38. LIBRARIES SDKS WRAPPERS CLIENTS @taylor_atx
  39. 39. 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
  40. 40. EMPATHY FAILURE BEGINNER’S MIND FAILURE @taylor_atx
  41. 41. 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
  42. 42. @taylor_atx
  43. 43. ERROR MESSAGES @taylor_atx
  44. 44. ERROR MESSAGES ARE AN OPPORTUNITY @taylor_atx
  45. 45. 3 H’S OF GOOD ERROR MESSAGES: HUMBLE HUMAN HELPFUL @taylor_atx
  46. 46. 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
  47. 47. HUMAN • Speak in human terms • Example: • Your API Key is invalid, please try a different key. @taylor_atx
  48. 48. 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
  49. 49. WRITING ERROR MESSAGES 1. Acknowledge 2. Apologize 3. Explain 4. Help @taylor_atx
  50. 50. 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
  51. 51. 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
  52. 52. HOW DO I GET OTHER TEAMMATES TO CONTRIBUTE TO DOCS? @taylor_atx
  53. 53. “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
  54. 54. MAKE SURE CONTRIBUTORS ARE VALUED & REWARDED @taylor_atx
  55. 55. SHOW THE BENEFITS @taylor_atx
  56. 56. GITHUB FOR DOCS • Continuous integration and automated testing • Issues • Incremental changes @taylor_atx
  57. 57. 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
  58. 58. 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
  59. 59. Community Engineer at Keen IO taylor@keen.io @taylor_atx TAYLOR BARNETT
  60. 60. 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/
  61. 61. 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

×