Recently, I read a post on the Digital Ocean blog (Documentation As An Open Source Practice) talking about best practices for documenting open source project repos (like Github). The main focus of the post was on providing community-focused documentation (code of conduct, contributors, etc.). I agree that those are good, but it does not tell the whole documentation story. The Write The Docs site has a terrific beginners guide to documentation for a software project. Here are some of my own tips I have passed on to other engineers.

• Pick a topic
  • What do I need to know to do my job?
  • Is it on the wiki?
  • “Handy tip: write down the things you learn so you don’t have to remember them.” (via @KenSmith)
• Identify your audience
  • Who are you writing for?
  • What should they know already?
  • What do they need to know?
• Creating instructions or a checklist for a task
  • Perform the task and take notes as you go
  • Add setup details as needed
  • Add equipment/tool list if applicable
  • Print your initial draft, then repeat the task following your instructions
  • Mark up the draft with additional information if needed to perform the task
  • Add the draft writeup to a wiki or other tool
  • Example – How to Write A HOW-TO document
• Final Thoughts
  • Writing things down is important
    • If it’s not written down, that information could be lost
  • Updating things is important too
    • Information can be written down, but incorrect or out of date
  • Break the writing down to make it easier to start
    • Use timeboxing (Example: write for no more than 15 minutes at a time)
    • Copy/paste can be your friend
      • Copying text from application windows
      • Screenshots
    • Keep a Word document open and type a running set of bullet items, then do some editing, then paste into a wiki page
  • It’s ok for your first draft to be shitty (link to Anne Lamott piece on writing)
  • Treat yourself after doing some writing!