The Art Of Documentation for Open Source Projects
Download as PPTX, PDF2 likes409 views
The document discusses the challenges and strategies for creating effective documentation in open source projects, emphasizing the importance of user experience and clarity. It highlights different reading patterns and the role of documentation in supporting users throughout their journey, from initial engagement to potential contribution. Ultimately, good documentation is framed as a key competitive advantage that fosters confidence and trust within the user community.
The Art Of Documentation for Open Source Projects
- 2. The Open Source Survey is an open data project by GitHub and collaborators from academia, industry, and the broader open source community
- 3. @Ben_Hall / Blog.BenHall.me.uk Microsoft MVP â Cloud and Datacenter Management Founder of Katacoda.com WHOAMI?
- 4. Learn via Interactive Browser-Based Labs Katacoda.com
- 8. Agenda? 1. Users journey with Open Source Projects 2. Documentation to support Users 3. Examples/Inspiration of documentation
- 17. Janet has joined a new team! New ideas, new concepts. New open source projects Potential New User
- 18. No-One Reads No-One Writes Everyone Wants Docs
- 21. Reading Large Blocks Of Text is difficult Writing Large Blocks Of Text is painful
- 22. Commitment pattern (rare) Consists of fixating on almost everything on the page.
- 23. Layer-cake pattern Occurs when the eyes scan headings and subheadings and skip the normal text below
- 24. 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.
- 25. "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." https://www.mnn.com/lifestyle/arts-culture/stories/why-your- brain-can-read-jumbled-letters
- 29. Think of target audience Remember Janet!
- 30. Does this project solve my problem? Will the project help my career?
- 31. Readme.md will likely be the first experience for many users
- 33. âJust deploy using Cloud Formationâ
- 34. Aim: How can you showcase the value without large commitment from the user?
- 35. Short Videos / Gifs
- 36. Examples!
- 43. Empower people to feel confident and build trust Isnât this fundamentally the aim of documentation?
- 46. Be careful of assuming prior knowledge
- 51. Not everyoneâs first language is English
- 52. Inclusive Languages âJustâ, âEasyâ, âSimpleâ, âAnyone can do it!â âHeâ, âHimâ đĄ
- 53. Janet loves your project! It solves their problems! Active User!
- 55. 1| SOLVE MY OTHER PROBLEMS đ¤ 2| OH NO! ITâS BROKEN đĽ
- 56. 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
- 63. đđĽđż Something has gone wrong! What documentation do you need when everything is on fire?
- 64. Remember the userâs emotions at this point
- 66. The best documentation is the one you donât have to write
- 68. The đĽ is out Janet has new experiences to share Potential New Contributor đ
- 70. Code of Conduct
- 71. License
- 83. Longer form content! Design Docs, Reference API
- 85. Janet has made a impact to the community. Ready to become a maintainer! Potential New Maintainer đ
- 98. WHAT IS THE ART OF DOCUMENTATION?? 3 key points
- 99. 1| Developers Experiment đś Your documentation should support this mindset
- 100. 2| Users get into trouble đĽ Where might users become struck?
- 101. 3| Encourage Contributors đ Everyone has a story to tell.