Carmen Chung How to write tech documentation that will save your career ! @carmenhchung

✅ 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

✅ 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

@carmenhchung

✅ 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

@carmenhchung

No content

✅ 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

✅ 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

@carmenhchung

✅ 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

No content

No content

No content

No content

No content

No content

No content

✅ 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

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.

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.

Tip #8: Cover the 4 Ws + How. @carmenhchung ✅ Be specific about tasks. - List actual attributes that need to be created.

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.

Tip #8: Cover the 4 Ws + How. @carmenhchung ✅ Keep a paper trail of all requests. - Tag people.

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.

No content

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