Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Top 6 Tips For Writing Technical Documentation

61857dafbd287b3027c4dcea9008ad3c?s=47 Carmen Chung
September 21, 2019

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.

61857dafbd287b3027c4dcea9008ad3c?s=128

Carmen Chung

September 21, 2019
Tweet

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
  6. None
  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
  10. None
  11. None
  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
  14. None
  15. None
  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