The art of documentation and readme.md
•Download as PPTX, PDF•
4 likes•394 views
This document discusses the 5 stages of documentation: Exploration, Getting Started, Onboarding, Guidance/Discovery, and Reference. It emphasizes that documentation needs to match how users learn and should begin during product exploration. The Readme.md file is important for setting the project's tone and showing value to new users within 9 minutes by explaining what problems it solves and how to get started. Managing documentation requires its own community and processes for feedback like automated example testing.
Recommended
More Related Content
What's hot
What's hot (17)
Similar to The art of documentation and readme.md
Similar to The art of documentation and readme.md (20)
More from Ben Hall
More from Ben Hall (20)
Recently uploaded
Recently uploaded (20)
The art of documentation and readme.md
- 1. The Art Of Documentation and Readme.md @Ben_Hall Ben@BenHall.me.uk Katacoda.com
- 4. The Art Of Documentation and Readme.md @Ben_Hall Ben@BenHall.me.uk Katacoda.com
- 6. Learn via Interactive Browser-Based Labs Katacoda.com
- 7. Agenda • User's Product Journey • How User's Learn • 5 Stages of Documentation • How it applies to Readme.md • Managing Docs
- 8. How documentation can help the adoption of your product/project Different to code documentation
- 10. The journey begins long before mycompany.com/docs
- 11. Not created once the product is complete
- 12. Users engage with your site, your examples, your demos before reading your documentation
- 17. Exploration Getting Started OnBoarding/Problem Solving Guidance/Discovery Reference One Minute 9 Minutes
- 22. “Call Us”
- 23. OnBoarding/Problem Solving Guidance/Discovery Reference
- 24. Maps to how users learn
- 31. Exploration Getting Started OnBoarding/Problem Solving Guidance/Discovery Reference How to start creating documentation
- 33. This is your first piece of documentation
- 34. “Why should I care?”
- 44. Stage 2: Getting Started
- 45. 9 minutes left for users to identify value
- 46. “Do you solve my problem?”
- 47. Can your product relate to my dream/problem?
- 62. Broken Samples
- 63. Video Content
- 67. “Congratulations! I want to use your product”
- 68. How quickly can you get them started?
- 69. Provision API keys, access tokens, downloads
- 75. Stage 4: Guidance and Discovery
- 76. “Your product is solving my problem. What other problems can you solve?”
- 95. But what about Readme.md?
- 98. Sets the tone
- 100. What should be included? • Why project exists • Show them what problems it solves • Show them how to get started • Tell them how to be successful
- 105. Building community
- 106. Open Source Focused • Include Contributors guidelines • Include License • Include where to discuss the project
- 107. “Just Read The Tests”
- 108. Managing Docs
- 109. Separate Project
- 113. Build it’s own community
- 114. Kubernetes sig-docs
- 117. Automated tests for your examples?
- 118. Make it easy to provide feedback
- 123. Who creates the “best” documentation?
Editor's Notes
- Not created once the product is complete
- The art of documentation is making your docs feel part of your product
- Sadly most documentation is the Owl
- Trust