Courses Company Wiki Best Practices Lesson 5

How to Write Like a Pro

Great documentation doesn’t require perfect writing. So don’t let the writing part feel daunting. The most important factor when it comes to great documentation is that the reader can understand what you’ve shared. Here are some tips to make sure you’re being as clear as possible:

Keep it simple

Your writing should be clear and to the point. If you use jargon, define those terms and/or link to a definition online. Better yet, build another Tettra page where you define various terms and create an internal page link to it. Don’t try to put everything on one page…readers can feel overwhelmed upon seeing massively long pages. If there’s a lot you want to cover, create different, related pages, and link strategically from one to the other.

Show, don’t tell

A picture tells a thousand words, and a video tells a million. Wherever possible, use screenshots to help orient people. If you’re describing how to use a piece of software, try to include a video or gif of how to use it. If you’re telling people how to get somewhere, include an image of the map or route.

Ask someone to follow your documentation

Once you’ve documented something, ask a teammate to read through what you’ve written to make sure everything is clear. If you’ve documented a process, have someone follow your steps to see if you’ve overlooked anything.

Create templates for routine work

If there are certain things you do again and again, make it easy for your team to document those items by using templates. Here are some processes that other Tettra teams like to standardize with templates:
  • Weekly standups
  • Monthly or quarterly goals
  • Product briefs
  • Engineering sprint priorities
  • Marketing campaign components
  • Recruiting and hiring procedures
  • New hire onboarding tasks

Your assignment

Pick a process that you know well, and draft a Tettra page about it. Try embedding a video or image. Share this page with someone else, and ask them to give you feedback on whether it was clear and whether they were able to follow the process, using your documentation. Don't cheat! If they have to ask you for clarification along the way, update the page to include this new set of details.