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.

Write Your Docs Like Nobody Reads Them

41 views

Published on

The dirty secret of docs is that it’s rare for folks to actually sit down and read the manual. Devs engage with our docs via search, support, and stack overflow. I’ll share strategies for creating paths to our docs and how we make it easy for users to efficiently navigate our docs once they arrive.

Published in: Technology
  • Login to see the comments

  • Be the first to like this

Write Your Docs Like Nobody Reads Them

  1. 1. Write your Docs Like Nobody Reads Them 1 @ShyRuparel API The Docs Chicago April 8th 2019 1
  2. 2. Shy Ruparel Developer Evangelist | Contentful @ShyRuparel He/Him 2
  3. 3. How do folks engage with documentation? @ShyRuparel3
  4. 4. Not always by reading it @ShyRuparel4
  5. 5. RTFM @ShyRuparel55
  6. 6. When you use RTFM, you’re saying, “Not only am I not going to help you, but I also want to make sure that you feel ashamed about your inability to help yourself.” -April Wensel medium.com/compassionate-coding/its-time-to-retire-rtfm- 31acdfef654f @ShyRuparel6
  7. 7. 7 @ShyRuparel7 How do people engage with documentation?
  8. 8. 8 @ShyRuparel8 How do people learn?
  9. 9. Reading/Writing Learning @ShyRuparel9
  10. 10. Visual Learning @ShyRuparel10
  11. 11. Auditory Learning @ShyRuparel11
  12. 12. Kinesthetic learning @ShyRuparel12
  13. 13. Contentful Documentation 13 @ShyRuparel13
  14. 14. Contentful @ShyRuparel1414
  15. 15. Areas of documentation 15 @ShyRuparel
  16. 16. What part of the manual? @ShyRuparel1616
  17. 17. Reducing Friction around Information Discovery 17 @ShyRuparel17
  18. 18. Developer Empowerment 18 @ShyRuparel18
  19. 19. Content Discovery 19 @ShyRuparel19
  20. 20. Coding is at least 50% knowing how to google 20 @ShyRuparel20
  21. 21. Documentation Discovery @ShyRuparel2121
  22. 22. Internal Search @ShyRuparel22
  23. 23. Internal Search @ShyRuparel23
  24. 24. Documentation doesn’t need to just be static content 24 @ShyRuparel24
  25. 25. Clicking Things @ShyRuparel25
  26. 26. Copy/Paste ready samples @ShyRuparel2626
  27. 27. Video @ShyRuparel27
  28. 28. Don’t be afraid to delete content when it gets stale 28 @ShyRuparel28
  29. 29. Extending your Docs 29 @ShyRuparel29
  30. 30. Developer Community 30 @ShyRuparel30
  31. 31. Let’s chat about Stack Overflow @ShyRuparel3131
  32. 32. Developers Use Stack Overflow @ShyRuparel32
  33. 33. Stack Overflow is better at SEO than I am @ShyRuparel33
  34. 34. Optimize your time spent on Stack Overflow 34 @ShyRuparel34
  35. 35. Link back to your own docs when you answer questions @ShyRuparel3535
  36. 36. Developer Portal @ShyRuparel3636
  37. 37. Chatrooms 37 @ShyRuparel37
  38. 38. Slack @ShyRuparel3838
  39. 39. Automation @ShyRuparel3939
  40. 40. Spend Time with your Community 40 @ShyRuparel40
  41. 41. Meetups 41 @ShyRuparel
  42. 42. Log where folks are struggling 42 @ShyRuparel42
  43. 43. Create Content to reduce struggle @ShyRuparel4343
  44. 44. Support Different Learning Styles ● Video ● Search ● 1-click API Calls ● Copy / Paste ready samples ● Deprecated stale content 44 ● Reading/Writing ● Visual ● Auditory ● Kinesthetic More than Text Beyond the Docs ● Stack Overflow ● Slack ● Meetups ● Document and Evolve Summary @ShyRuparel
  45. 45. Questions? @ShyRuparel Slides: github.com/shy/talks

×