How to write technical documentation that will save your career

Talk given at RubyConfAU2020 in Melbourne, Australia.

In this presentation, ex-corporate lawyer, Carmen Chung, will give you her top tips for writing tech documentation that people (including yourself!) will come back to, time and time again. Docs that are easy to understand, well structured, and a little bit fun.

Transcript

1. Carmen Chung How to write tech documentation that will save your career ! @carmenhchung
2. ✅ Make your title “SEO” friendly. Write clear, precise and relevant titles. e.g. “How To Remove Columns From Our Database” ❌ But that doesn’t mean clickbait titles! e.g. “4 ways to remove columns from our database...the final one will shock you!” Tip #1: Pick your title carefully. @carmenhchung
3. ✅ Have an index. - Make it clickable. ✅ Offer an introduction. - Explain what this document is going to do. - Mention required pre-reading. - Add TL;DR section if needed. ✅ Break up text. - Structure the document in easy-to-digest chunks. - Use screenshots, flowcharts, and diagrams. - Consider extracting information. Tip #2: Provide clear structure. @carmenhchung
4. @carmenhchung
5. ✅ Make updating docs part of the process. - Add it to your pre-deploy checklist. ✅ Give context with dates. e.g. As of January 2019, the process for removing columns from our database is this… ⚠ [Update] As of September 2019, we have moved towards a “strong migrations” approach for removing database columns… ❌ Don’t leave updating to others! Tip #3: Update regularly. @carmenhchung
6. @carmenhchung
8. ✅ Format code…and explain what it does. e.g. “Run pip install big-tech-co-repo in Terminal, which will install our entire repository on your machine in the current folder you’re in.” ❌ Don’t include secrets. e.g. “Run the create-database command in Terminal and it will generate the credentials for you, which will look something along the lines of (but be different to) this: 1.URL: “https://big-tech-co.com/our-database” 2.Username: “dummy-database” 3.Password: “dummy-password” Tip #4: Make the most of code examples. @carmenhchung
9. ✅ Selectively commit short, clear commit messages. ❌ “WIP WIP WIP WIP WIP” ❌ “Please just pass for once.” ❌ “WHY YOU NO PASS!” ❌ ✅ Add detail to your PR description. - Have a Pull Request template that is automatically applied to every pull request that is opened. Tip #5: Refine commit messages and PRs. @carmenhchung
10. @carmenhchung
11. ✅ Comment code when it needs context. - e.g. Something is not done for a reason or something is done that seems out of the ordinary. ✅ Add TODOs if you will do… - Mention who is to do what, why they’re to do it, and when they’re to do it. ❌ Don’t just comment code because it’s difficult. Tip #6: Comment code where necessary. @carmenhchung
19. ✅ Cover all scenarios with context blocks. e.g. - When an account doesn’t have a user. - When an account has a user but the user has not yet selected their tier. - When an account has a user and the user is on a free tier. - When an account has a user and the user is on a paid tier. Tip #7: Write comprehensive specs. @carmenhchung
20. Tip #8: Cover the 4 Ws + How. @carmenhchung ✅ Write with precision and detail. - Who is to do what, by when, and why and how are they going to do it.
21. Tip #8: Cover the 4 Ws + How. @carmenhchung e.g. @DonaldTroll will create two pricing tiers today: one called “Free User” and one called “Paid User”. ✅ Write with precision and detail. - Who is to do what, by when, and why and how are they going to do it.
22. Tip #8: Cover the 4 Ws + How. @carmenhchung ✅ Be specific about tasks. - List actual attributes that need to be created.
23. Tip #8: Cover the 4 Ws + How. @carmenhchung e.g. The paid tier lets you: - read, create, update and destroy records. The free tier lets you: - only read records. ✅ Be specific about tasks. - List actual attributes that need to be created.
24. Tip #8: Cover the 4 Ws + How. @carmenhchung ✅ Keep a paper trail of all requests. - Tag people.
25. e.g. I spoke to @FrancoPM about this today (1 May 2019). He told me that as we have now finished the investor demo, we should turn off all the pricing tiers for now. I have done this. Don’t forget to re-activate this when we go live by setting the boolean “active” flag to true. Tip #8: Cover the 4 Ws + How. @carmenhchung ✅ Keep a paper trail of all requests. - Tag people.
27. Conclusion ! 1. Pick your title carefully. ✅ 2. Provide clear structure. 3. Update regularly. ✅ 4. Make the most of code examples. ✅ 5. Refine commit messages and PRs. ✅ 6. Comment code where necessary. ✅ 7. Write comprehensive specs. ✅ 8. Cover the 4 Ws + How. ✅ @carmenhchung