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.

The Art of Documentation and Readme.md for Open Source Projects

283 views

Published on

Delivered 6th December 2017 at Kubecon 2017, Austin, US

Published in: Technology
  • Be the first to comment

  • Be the first to like this

The Art of Documentation and Readme.md for Open Source Projects

  1. 1. The Art of Documentation and Readme.md for Open Source Projects @Ben_Hall Ben@BenHall.me.uk Katacoda.com
  2. 2. The Art of Documentation and Readme.md for Open Source Projects @Ben_Hall Ben@BenHall.me.uk Katacoda.com
  3. 3. @Ben_Hall / Blog.BenHall.me.uk WHOAMI?
  4. 4. Learn via Interactive Browser-Based Labs Katacoda.com
  5. 5. How documentation can transform the adoption of your product/project Different to code documentation
  6. 6. Where to begin?
  7. 7. https://twitter.com/samnewman/status/934185375291060224
  8. 8. https://twitter.com/joeerl/status/934473378601291776?s=09
  9. 9. The journey begins long before myproduct.com/docs
  10. 10. Exploration Getting Started OnBoarding/Problem Solving Guidance/Discovery Reference Product Adoption Journey Applies to both Website and Readme.md
  11. 11. Exploration Getting Started OnBoarding/Problem Solving Guidance/Discovery Reference
  12. 12. Stage 1: Exploration
  13. 13. “Why should I care?”
  14. 14. Stage 2: Getting Started
  15. 15. “Do you really solve my problem?”
  16. 16. “Download 10GB VM”
  17. 17. “Deploy using CloudFormation”
  18. 18. Asking for a large commitment before demonstrating you’re the right fit
  19. 19. Do I have curl installed? What about mobile/iPad? 🤔
  20. 20. Users understand what your product does, and experienced the dream!
  21. 21. Stage 3: Onboarding
  22. 22. “Congratulations! I want to use your product”
  23. 23. The best documentation is the one we don’t have to write.
  24. 24. People don’t read on the internet “He thinks he’s people!” (Archer)
  25. 25. Show/Hide Headers Button
  26. 26. https://beta.developer.spotify.com/documentation/web-playback-sdk/quick-start/#initializing-the-sdk
  27. 27. Hard to document === missing developer UX?
  28. 28. Build tooling to help? Kubeadm Why write documentation when you can automate it?
  29. 29. https://www.katacoda.com/courses/kubernetes/getting-started-with-kubeadm
  30. 30. Stage 4: Guidance and Discovery
  31. 31. “Your product is solving my problem. What other problems can you solve?”
  32. 32. Stage 5: Reference
  33. 33. Becoming an expert…
  34. 34. Exploration Getting Started OnBoarding/Problem Solving Guidance/Discovery Reference Clear Project Definition Interactive Demos/Examples Low barriers to get started Tutorials/Guides Long Form Reference
  35. 35. But what about Readme.md?
  36. 36. Sets the tone
  37. 37. <details> <summary><b>Examples</b></summary> <ul> <li> <a href="./examples/json-body-parsing">Parse JSON</a></li> <li> <a href="./examples/urlencoded-body-parsing">Parse urlencoded form (html `form` tag)</a></li> </ul> </details>
  38. 38. Build it’s own community
  39. 39. Make it easy to provide feedback
  40. 40. Who creates the “best” documentation?
  41. 41. https://betta.io/blog/2016/12/14/what-developer-experience-could-learn-from-lego/
  42. 42. @Ben_Hall Ben@BenHall.me.uk Blog.BenHall.me.uk www.Katacoda.com

×