Writing open-source documentation
at scale that isn't terrible:
Right the Docs
@vipulgupta2048
Who is dis Vipul?
- Write code @ balena
- Runs a blog & documentation initiative by the name of Mixster
- Leads content and stuff for PyCon India
- Recent pseudo-graduate no thanks to Covid
- Loves Party Parrots
@vipulgupta2048
Name a major open-source
project
with no docs
If docs are so important, then why am I giving this talk?
- Time spent in planning
- Cost of maintenance vs short term gain
- No dedicated team for docs
Right
The
Docs
Pick your battles
- Make peace with yourself that you can't document everything
- Plan before you document
- Review after you document
@vipulgupta2048
Break down the complex!
- Understanding user pain points through constant feedback
- Documenting core concepts as a reference section
- Slow is smooth, smooth is fast
@vipulgupta2048
Friction Logging!
- Ask your devs/contributors to use a new product/feature as an outsider/end-user
- Ask them to log details about their experience
- Remove friction as seen, iterate, repeat!
@vipulgupta2048
No assumptions whatsoever
- Just do an npm install for package y x z
- Deploy your virtual machine and follow the installation steps below
- Navigate to `beta` directory & run the command
- Give context, provide references, and cover edge cases and errors for better onboarding
@vipulgupta2048
Become a beginner again
- Skipping steps leads to confusion
- Break up your "Getting Started"
- Code snippets are a must
- Use inclusive language and catch unequal phrasing
@vipulgupta2048
Pick a template
Sticking to that template
- Take your time finding the right template for your current and future needs of the project
- Define a style guide & brand voice for your project
- Keep deployment pipelines simple for writers
@vipulgupta2048
Scaling
Them
Docs
Growing healthy documentation
- Sectioning off the docs
- Giving real examples
- Cookbooks
- Streamline information flow
- Product screenshots
@vipulgupta2048
- Step by step Tutorials
- Blogs
- Videos
- References
- Scaling the design
Taking Inspiration!
References & links
- 5 simple things you can do to improve OSS docs - Erin McKean
- Write the Docs Community Resouces & Slack
- Google's Technical Writing Course
- Eight Rules to good docs! - Orielly
- Friction Logging
- And, so many more.
@vipulgupta2048
When you realize you have the power to improve docs!
Danke scheon !!
Questions? Any feedback.
Mixster offer free consultation on your docs and ice-cream!
Vipul Gupta
OSS developer | Documentarian
On the web by @vipulgupta2048
Writing open-source documentation at scale that isn't terrible: Right the Docs @vipulgupta2048