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

@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

Made with Slides.com