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.

of

Things I Wish People Told Me About Writing Docs Slide 1 Things I Wish People Told Me About Writing Docs Slide 2 Things I Wish People Told Me About Writing Docs Slide 3 Things I Wish People Told Me About Writing Docs Slide 4 Things I Wish People Told Me About Writing Docs Slide 5 Things I Wish People Told Me About Writing Docs Slide 6 Things I Wish People Told Me About Writing Docs Slide 7 Things I Wish People Told Me About Writing Docs Slide 8 Things I Wish People Told Me About Writing Docs Slide 9 Things I Wish People Told Me About Writing Docs Slide 10 Things I Wish People Told Me About Writing Docs Slide 11 Things I Wish People Told Me About Writing Docs Slide 12 Things I Wish People Told Me About Writing Docs Slide 13 Things I Wish People Told Me About Writing Docs Slide 14 Things I Wish People Told Me About Writing Docs Slide 15 Things I Wish People Told Me About Writing Docs Slide 16 Things I Wish People Told Me About Writing Docs Slide 17 Things I Wish People Told Me About Writing Docs Slide 18 Things I Wish People Told Me About Writing Docs Slide 19 Things I Wish People Told Me About Writing Docs Slide 20 Things I Wish People Told Me About Writing Docs Slide 21 Things I Wish People Told Me About Writing Docs Slide 22 Things I Wish People Told Me About Writing Docs Slide 23 Things I Wish People Told Me About Writing Docs Slide 24 Things I Wish People Told Me About Writing Docs Slide 25 Things I Wish People Told Me About Writing Docs Slide 26 Things I Wish People Told Me About Writing Docs Slide 27 Things I Wish People Told Me About Writing Docs Slide 28 Things I Wish People Told Me About Writing Docs Slide 29 Things I Wish People Told Me About Writing Docs Slide 30 Things I Wish People Told Me About Writing Docs Slide 31 Things I Wish People Told Me About Writing Docs Slide 32 Things I Wish People Told Me About Writing Docs Slide 33 Things I Wish People Told Me About Writing Docs Slide 34 Things I Wish People Told Me About Writing Docs Slide 35 Things I Wish People Told Me About Writing Docs Slide 36 Things I Wish People Told Me About Writing Docs Slide 37 Things I Wish People Told Me About Writing Docs Slide 38 Things I Wish People Told Me About Writing Docs Slide 39 Things I Wish People Told Me About Writing Docs Slide 40 Things I Wish People Told Me About Writing Docs Slide 41 Things I Wish People Told Me About Writing Docs Slide 42 Things I Wish People Told Me About Writing Docs Slide 43 Things I Wish People Told Me About Writing Docs Slide 44 Things I Wish People Told Me About Writing Docs Slide 45 Things I Wish People Told Me About Writing Docs Slide 46 Things I Wish People Told Me About Writing Docs Slide 47 Things I Wish People Told Me About Writing Docs Slide 48 Things I Wish People Told Me About Writing Docs Slide 49 Things I Wish People Told Me About Writing Docs Slide 50 Things I Wish People Told Me About Writing Docs Slide 51 Things I Wish People Told Me About Writing Docs Slide 52 Things I Wish People Told Me About Writing Docs Slide 53 Things I Wish People Told Me About Writing Docs Slide 54 Things I Wish People Told Me About Writing Docs Slide 55 Things I Wish People Told Me About Writing Docs Slide 56 Things I Wish People Told Me About Writing Docs Slide 57 Things I Wish People Told Me About Writing Docs Slide 58 Things I Wish People Told Me About Writing Docs Slide 59 Things I Wish People Told Me About Writing Docs Slide 60 Things I Wish People Told Me About Writing Docs Slide 61 Things I Wish People Told Me About Writing Docs Slide 62 Things I Wish People Told Me About Writing Docs Slide 63
Upcoming SlideShare
What to Upload to SlideShare
Next
Download to read offline and view in fullscreen.

5 Likes

Share

Download to read offline

Things I Wish People Told Me About Writing Docs

Download to read offline

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.

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all

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
  • AndyDavies

    Feb. 13, 2018
  • episod

    Feb. 6, 2018
  • pawnpar245

    Dec. 18, 2017
  • ViktoriiaTerebushka

    Nov. 8, 2017
  • haberryan

    Nov. 3, 2017

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.

Views

Total views

1,745

On Slideshare

0

From embeds

0

Number of embeds

162

Actions

Downloads

11

Shares

0

Comments

0

Likes

5

×