Documentation Writing (for coders)

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.

61857dafbd287b3027c4dcea9008ad3c?s=128

Carmen Chung

May 15, 2020
Tweet

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

  4. None
  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
  6. None
  7. None
  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!” ❌
  14. None
  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.
  16. None
  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
  18. None
  19. None
  20. None
  21. None
  22. None
  23. None
  24. None
  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