Effective Documentation: The Key to Open Source Growth
Bolaji Ayodeji

Developer Advocate at Commerce Layer
Talk Contents

  • Introduction to OS Documentation
  • The Myths of Open Source
  • Understanding User Personas
  • The Effective Docs Strategies
  • Bad Documentation Checklist
  • Good Documentation Checklist
  • Useful Documentation Tools
  • What Next?
Introduction to OSS Documentation
In open source, documentation is the information that describes a project to its users and contributors.
The Myths of
Open Source
  • Open source is the responsibility of the creator alone
  • Open source is just about code
  • Open source software is less secure than proprietary software
Understanding User Personas

 

  • 👥 End Users
  • 👨🏾‍💻 Developers
  • 👩‍🎨 Designers
  • ✍🏾 Technical Writers
  • 🧑🏼‍💼 Program Managers
  • 💰 Financial Contributors
What do they want?

  • What do they want to get out of your project?
  • What solutions(s) does your project offer?
  • What could be their initial visit mindset?
Where are they coming from?

  • Search engine
  • Social media
  • Backlinks
  • Package managers
How much time will they dedicate?

  • What do they want?
  • How fast do they want it?
  • How fast can your Docs serve them?
  • How fast can you respond to their issue(s)?
  • How satisfied will they be?
How technical savvy are they (Users && Contributors)?

  • Newbie
  • Beginner
  • Junior
  • Intermediate
  • Expert
  • Distinguished
The Effective Docs Strategies
Define a documentation vision for your project
What are the core reasons for people engaging with your project?
Define your target state
Be clear and realistic about your documentation goals.
Do a gap analysis between the current and target state
Analyze your current documentation state and target state. Ensure to document the differences.
Introduce approaches and/or processes to reach the target state
Set up and execute your documentation processes
Start small and prioritize sustainability.
Sustainability
Make sure you have sufficient plan, team, or community to maintain your documentation.
Quality over quantity
Leverage other techniques aside “text-related content”
  • Visual Documentation
  • Use Cases
  • Working Samples
  • Testimonials
  • Metrics
Build a community around your documentation
Attract collaborators, sell the vision, recruit help and simplify the contribution process.
Automate and track revision history
Bad Documentation Checklist

 

  • Doesn’t scale with your project
  • Repeats patterns
  • Ambiguous
  • Not inclusive
  • Missing contributors guide
  • Doesn’t include support link(s)
  • Doesn’t respond to user issue(s) in time
Good Documentation Checklist
  • Why was this project created?
  • What problem(s) does it solve?
  • How can I get started with it?
  • Where has this project been used?
  • Who is using it?
  • Some live use cases
  • How can I contribute?
  • Where can I get help?
Useful Documentation Tools
What next?
Define a documentation vision for your project and prepare goals.
Build a community around your documentation and ensure you prioritize sustainability at the early stages of your project.
Your documentation should provide users with a roadmap to using your project
Documentation helps your users succeed with your software, empowers them to be self-sufficient, enables them to give further feedback, and is the organizational backbone of your project.
Thank you!
Bolaji Ayodeji

Developer Advocate at Commerce Layer