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)

✅ 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

✅ 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

✅ 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

✅ 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

No content

✅ 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

✅ 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

✅ 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

No content

No content

✅ 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

✅ 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

No content

No content

#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