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 for Open Source Projects


Published on

Delivered at Kubecon US 2018 by Ben Hall. Watch the recording at

In this talk, Ben uses his expertise of building an Interactive Learning Platform to highlight The Art of Documentation. The aim of the talk is to help open source contributors understand how small changes to their documentation approach can have an enormous impact on how users get started.

Published in: Technology
  • Login to see the comments

The Art Of Documentation for Open Source Projects

  2. 2. The Open Source Survey is an open data project by GitHub and collaborators from academia, industry, and the broader open source community
  3. 3. @Ben_Hall / Microsoft MVP – Cloud and Datacenter Management Founder of WHOAMI?
  4. 4. Learn via Interactive Browser-Based Labs
  5. 5.
  6. 6.
  7. 7. Agenda? 1. Users journey with Open Source Projects 2. Documentation to support Users 3. Examples/Inspiration of documentation
  8. 8. Documentation Potential Users Implementers Contributors Maintainers
  9. 9. Documentation Potential Users Implementers Contributors Maintainers
  10. 10. Documentation Potential Users Implementers Contributors Maintainers
  11. 11. Documentation Potential Users Implementers Contributors Maintainers
  12. 12. Documentation Potential Users Implementers Contributors Maintainers
  13. 13. Janet has joined a new team! New ideas, new concepts. New open source projects Potential New User
  14. 14. No-One Reads No-One Writes Everyone Wants Docs
  15. 15. web-content/
  16. 16. Reading Large Blocks Of Text is difficult Writing Large Blocks Of Text is painful
  17. 17. Commitment pattern (rare) Consists of fixating on almost everything on the page.
  18. 18. Layer-cake pattern Occurs when the eyes scan headings and subheadings and skip the normal text below
  19. 19. Spotted pattern Consists of skipping big chunks of text and scanning as if looking for something specific, such as a link, digits, a particular word.
  20. 20. "It deosn't mttaer in waht oredr the ltteers in a wrod are, the olny iprmoetnt tihng is taht the frist and lsat ltteer be at the rghit pclae. The rset can be a toatl mses and you can sitll raed it wouthit porbelm. Tihs is bcuseae the huamn mnid deos not raed ervey lteter by istlef, but the wrod as a wlohe." brain-can-read-jumbled-letters
  21. 21. when-I-am-reading
  22. 22. when-I-am-reading
  23. 23. Think of target audience Remember Janet!
  24. 24. Does this project solve my problem? Will the project help my career?
  25. 25. will likely be the first experience for many users
  26. 26. “Download 10GB VM”
  27. 27. “Just deploy using Cloud Formation”
  28. 28. Aim: How can you showcase the value without large commitment from the user?
  29. 29. Short Videos / Gifs
  30. 30. Examples!
  31. 31. Empower people to feel confident and build trust Isn’t this fundamentally the aim of documentation?
  32. 32. Competitive Advantage
  33. 33. Be careful of assuming prior knowledge
  34. 34.
  35. 35. Not everyone’s first language is English
  36. 36. Inclusive Languages “Just”, “Easy”, “Simple”, “Anyone can do it!” “He”, “Him” 😡
  37. 37. Janet loves your project! It solves their problems! Active User!
  38. 38. Documentation Requirements Change
  40. 40. What else is possible? Asking questions about implementation How do I solve particular problems? Very similar to exploration when getting started. Can assume prior knowledge
  41. 41. 🙀🔥😿 Something has gone wrong! What documentation do you need when everything is on fire?
  42. 42. Remember the user’s emotions at this point
  43. 43. StackOverflow? Github Issues?
  44. 44. The best documentation is the one you don’t have to write
  45. 45. The 🔥 is out Janet has new experiences to share Potential New Contributor 🙌
  46. 46. Community and Contributor guidelines
  47. 47. Code of Conduct
  48. 48. License
  49. 49.
  50. 50. Longer form content! Design Docs, Reference API
  51. 51. Janet has made a impact to the community. Ready to become a maintainer! Potential New Maintainer 🙌
  52. 52. WHAT IS THE ART OF DOCUMENTATION?? 3 key points
  53. 53. 1| Developers Experiment 🐶 Your documentation should support this mindset
  54. 54. 2| Users get into trouble 🔥 Where might users become struck?
  55. 55. 3| Encourage Contributors 🙌 Everyone has a story to tell.