I <3 Documentation

Hello Internet stranger! Welcome to the documentation celebration party! Documentation is awesome but too commonly underappreciated so we are having a party for documentation and for those who take the time to write documentation!!!

Documentation is about showing your work so that others can understand and replicate it.

Documentation is accessible. Share it with others!

Documentation is never complete — it's better to ship it even it you don't feel ready. Also, it can grow and change as others react to it.

Documentation is honest. It's OK to note where you're not confident your documentation is correct. It's also important to record which parts of the project were difficult.

Examples of documentation

• Setting up a new development environment and sharing all the steps you took
• Hacking on a side project and explaining how to replicate it step-by-step
• Facing a new challenge and writing an article or blog post about how you overcame it
• Konmari’ng your home and vlogging the process
• Creating a painting and showing the concept sketches leading up to the final painting
• Building an experimental at-home method of growing a liver and writing up how you did it with pictures
• Sourcing a new printer for your artwork* and writing a post explaining how to evaluate and establish a relationship*
• Doing science and sharing your lab notebook

Benefits

Here are all the reasons documentation is awesome so you can tell your friends and invite them to the documentation writing brigade!

• For the individual
  • Scale yourself & save time: Documentation is scalable! Instead of 3 random people seeing your work and asking three individual questions, you write the documentation once and save time.
  • Find mistakes (debug) Helps you catch errors you may have missed and trace the cause
  • Solidify your own knowledge: Reflection is an opportunity to solidify your own understanding and find ways to innovate.
  • Bonus tip for people in machine learning! Machine learning is like science where keeping a lab notebook will help you keep track of your experiments
  • Notes for yourself! You have instructions for yourself if you forget esp after a vacation :)
  • Make friends! Find your community even if it’s just one other person! :)
• For the individual (longterm)
  • Practice essential skills: If your hope is to grow your influence over the course of your career, good writing skills are essential and documentation is a good opportunity to do this
  • Build your brand
  • Personal satisfaction: Look back in years and see how much you’ve grown
• For the community
  • Strengthen the community: Talks and communication are the backbone of a technical community
  • Community Growth: Encouraging more documentation grows the community → you present more material and you might hit more audiences
  • Immortalize the knowledge: It’s sad to say, but not everyone will be around forever and it’d suck to have knowledge locked up in people’s heads
  • Helps you create a more global community
• Save the world
  • Break the silos: By making more diverse introductory material available, you promote collaboration between different technical systems
  • Fight Imposter syndrome
  • Diversity! Representation! Encouraging more documentation grows the community → you present more material and you might hit more audiences. There are lots of cosplayers and lots of ML people, but not many ML cosplayers.
• Fun
  • Leads to surprises because you don’t know who is interested

FAQs

• My project isn’t interesting enough to document / similar things have been done before!
  • This is fine! 90% of your audience is a beginner. Maybe your documentation will be the right introduction to inspire and ignite a spark on someone else’s journey!
• But my documentation will too quickly go out of date!
  • Date your stuff
  • Snapshot documentation
• I don’t have time
  • Take pictures as you go along
  • Brainstorm on paper: write notes to yourself as you are figuring things out
  • Take copious notes
  • Set expectations to not have to maintain the documentation
  • Documentation is never complete
• Pitfalls / Negatives (primarily with software)
  • Too many docs can be confusing.
  • Mark deprecated as code is deprecated
  • Link to other documentation that you are aware of
  • Even better check the documentation in with your code in the same VCS
• I don’t have good writing skills!
  • Writing skills are hard and take time to develop. You probably have good writing skills compared to most people in your discipline if you care about documentation.
  • You can also supplement with photos
• How can I reward and encourage people I work with to write documentation?
  • Verbally recognize people for writing documentation
  • Encourage people to thank each other when they find each others’ documentation helpful

Express your love for documentation!

• Buy a sticker!
• Submit a testimonial!
• Sign up for our mailing list! Want to hear about joyful documentation-related happenings? We don't have any plans to send emails right now, but if we think of things we'd like to share with you, we promise we won't send more than one email a month.

Made with <3 by Ruth Grace Wong and jenbuilds.