Top 6 Tips For Writing Technical Documentation

In this presentation, ex-corporate lawyer, Carmen Chung, will give you her top six 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. Top 6 Tips For Writing Tech Documentation 
 That Will Save Your Career (from someone who used to do it for her career) ! Carmen Chung (@carmenhchung)
2. ✅ Make your title “SEO” friendly. Write clear, precise and relevant titles. e.g. “How To Remove Columns From Our Database” ❌ Avoid in-jokes / references that can become dated. e.g. “Guide to Project Kondo” ❌ Save click-bait for blogs / conference talks (maybe). e.g. “4 ways to remove columns from our database...the final one will shock you!” Tip #1: Have a clear title and structure. @carmenhchung
3. ✅ Provide an index. - Make it clickable. ✅ Use clear headings and subheadings. - Structure the document in easy-to-digest chunks. - Collapsable sections. - Use bullet points. - Use screenshots and flowcharts to break up chunky text. - Should you be extracting some of the information? - Insert links to other docs where necessary. ✅ Offer an introduction. - Include points that are crucial. - Mention required pre-reading/required knowledge. - Add TL;DR section if needed. Tip #1: Have a clear title and structure. @carmenhchung
4. ✅ Give context by mentioning today’s date. e.g. “As of January 2019, the process for removing columns from our database is this…” ✅ Use strikethrough when things change. 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. This means that...” ✅ Make updating docs part of the process. - Add it to your pre-deploy checklist, like a Github Pull Request template. ❌ Don’t leave updating to someone else if you can do it! Tip #2: Update regularly. @carmenhchung
5. ✅ Format code. e.g. Run pip install our-repo - Use code snippets / embedded code pens (if relevant). ✅ Explain what the code does. e.g. “Run pip install our-repo in Terminal, which will install our entire repository on your machine in the current folder you’re in.” ❌ Don’t include secrets / credentials. e.g. “Run the create-database command in Terminal and it will generate the database URL, username and password 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: “database” 3. Password: “password”
 Tip #3: Make use of code examples. ❌ @carmenhchung
7. ✅ Write short, clear commit messages. e.g. “ Fix bug by removing association between account and pricing tier models.” - Use selective committing. ✅ Document pre, during, and post deploy tasks - preferably in your PR description. - Have a Pull Request template that is automatically applied to every pull request that is opened. ✅ Use tags and links. - Link to other PRs and docs (e.g. project specs) where relevant, and tag people. e.g. “@FrancoForPM says this is approved for merging to production, subject to #1101 being merged.” Tip #4: Utilise commit messages and PRs. @carmenhchung
8. ✅ Comment code when it needs context. - e.g. something not done for a reason or something is done that seems out of the ordinary. ✅ Add TODOs if absolutely required. - 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 to understand. - Consider whether you need to refactor! ❌ Don’t just comment code because you can. Tip #5: Comment code where necessary. @carmenhchung
9. ✅ Comment code when it needs context. - e.g. something not done for a reason or something is done that seems out of the ordinary. ✅ Add TODOs if absolutely required. - 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 to understand. - Consider whether you need to refactor! ❌ Don’t just comment code because you can. Tip #5: Comment code where necessary. @carmenhchung
12. ✅ Think about specs before you code. - Specs actually give you confidence in your code and help people understand what you’ve done and why. ✅ Cover all scenarios and write the context blocks first. 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. ❌ Don’t be inconsistent in how you write specs. e.g. Don’t do “when the associated pricing_tier is a paid tier” in one line and then “when the pricing tier association is free” in the next. Tip #6: Write comprehensive specs. @carmenhchung
13. ✅ Write with precision and detail. - Who. What. When. Where. Why. How. ✅ Be specific about who is doing what. - Tag the person - for example, “@DonaldTroll will create two tiers: one called “Free User” and one called “Paid User”. If these names change in the future, I will create a new ticket for @DonaldTroll to update them.” ✅ Keep a paper trail of all requests. 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 turned the boolean “active” flag from “true” to “false”. Don’t forget to re- activate this by setting the flag to “true” when this goes live.” Bonus tip: Detail the 5 Ws + How. ❌ @carmenhchung
16. #1: Have a clear title and structure. ✅ #2: Update regularly. ✅ #3: Optimise code examples. ✅ #4: Utilise commit messages and PRs. ✅ #5: Comment code where necessary. ✅ #6: Detail the 5 Ws + How. ✅ Conclusion @carmenhchung @carmenhchung /carmenhchung carmenhchung.com