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. 2.
  2. 4.
  3. 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
  4. 6.
  5. 7.
  6. 9.

    Commit messages CLARITY & BREVITY ✅ Write short, clear commit

    messages. ❌ “WIP WIP WIP WIP WIP” @carmenhchung
  7. 10.

    Commit messages CLARITY & BREVITY ✅ Write short, clear commit

    messages. ❌ “WIP WIP WIP WIP WIP” ❌ “Please just work for once.” @carmenhchung
  8. 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
  9. 12.

    Commit messages CLARITY & BREVITY ✅ Write short, clear commit

    messages. ❌ “WIP WIP WIP WIP WIP” ❌ “Please just work for once.” ❌ “WHY YOU NO WORK!” ❌
  10. 13.

    Commit messages CLARITY & BREVITY ✅ Write short, clear commit

    messages. ❌ “WIP WIP WIP WIP WIP” ❌ “Please just work for once.” ❌ “WHY YOU NO WORK!” ❌
  11. 14.
  12. 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.
  13. 16.
  14. 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
  15. 18.
  16. 19.
  17. 20.
  18. 21.
  19. 22.
  20. 23.
  21. 24.
  22. 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