Documentation Writing (for coders)

Talk given to Coder Academy (AU) cohort in May 2020.

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. Documentation Writing (for coders) Carmen Chung @carmenhchung
2. Types of documentation Code comments. Commit messages. Pull Request descriptions. How To/Reference Guides. Blog posts. @carmenhchung
3. @carmenhchung
5. Code comments CONTEXT ✅ Comment code when it needs context. TODOS ✅ Add TODOs if something is to be done within a short period of time afterwards. DIFFICULTY ❌ Don’t just comment code because it’s difficult. @carmenhchung
8. Commit messages CLARITY & BREVITY ✅ Write short, clear commit messages. @carmenhchung
9. Commit messages CLARITY & BREVITY ✅ Write short, clear commit messages. ❌ “WIP WIP WIP WIP WIP” @carmenhchung
10. Commit messages CLARITY & BREVITY ✅ Write short, clear commit messages. ❌ “WIP WIP WIP WIP WIP” ❌ “Please just work for once.” @carmenhchung
11. Commit messages CLARITY & BREVITY ✅ Write short, clear commit messages. ❌ “WIP WIP WIP WIP WIP” ❌ “Please just work for once.” ❌ “WHY YOU NO WORK!” @carmenhchung
12. Commit messages CLARITY & BREVITY ✅ Write short, clear commit messages. ❌ “WIP WIP WIP WIP WIP” ❌ “Please just work for once.” ❌ “WHY YOU NO WORK!” ❌
13. Commit messages CLARITY & BREVITY ✅ Write short, clear commit messages. ❌ “WIP WIP WIP WIP WIP” ❌ “Please just work for once.” ❌ “WHY YOU NO WORK!” ❌
15. Pull Requests TEMPLATE ✅ Description of what you’ve done. ✅ Checklist of things you need to do. ✅ Document pre, during, and post deploy tasks. @carmenhchung ROLLBACK! ✅ Go for the smallest PR that makes sense.
17. How To Guides TITLE ✅ Make your title “SEO” friendly. STRUCTURE ✅ Add a Table of Contents / Index. ✅ Have an introduction. ✅ Break up chunky text. ✅ Format your code snippets. TIMELINESS ✅ Update regularly. ✅ Give context. @carmenhchung
25. Blogging VOICE ✅ Use a consistent voice. ✅ Consider your audience. FORUM ✅ Don't be afraid of publishing on multiple platforms. SOCIAL MEDIA ✅ Use social media to publicise your work. @carmenhchung
26. /CARMENCHUNG THANK YOU @CARMENHCHUNG WWW.CARMENHCHUNG.COM HTTP://BIT.LY/SAMPLE-PR-TEMPLATE