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
   

   View Slide

2. Types of
   documentation
   Code comments.
   Commit messages.
   Pull Request descriptions.
   How To/Reference Guides.
   Blog posts.
   @carmenhchung
   

   View Slide

3. @carmenhchung
   

   View Slide

4. View Slide

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
   

   View Slide

6. View Slide

7. View Slide

8. Commit
   messages
   CLARITY & BREVITY
   ✅ Write short, clear commit messages.
   @carmenhchung
   

   View Slide

9. Commit
   messages
   CLARITY & BREVITY
   ✅ Write short, clear commit messages.
   ❌ “WIP WIP WIP WIP WIP”
   @carmenhchung
   

   View Slide

10. Commit
    messages
    CLARITY & BREVITY
    ✅ Write short, clear commit messages.
    ❌ “WIP WIP WIP WIP WIP”
    ❌ “Please just work for once.”
    @carmenhchung
    

    View Slide

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
    

    View Slide

12. Commit
    messages
    CLARITY & BREVITY
    ✅ Write short, clear commit messages.
    ❌ “WIP WIP WIP WIP WIP”
    ❌ “Please just work for once.”
    ❌ “WHY YOU NO WORK!”
    ❌

    View Slide

13. Commit
    messages
    CLARITY & BREVITY
    ✅ Write short, clear commit messages.
    ❌ “WIP WIP WIP WIP WIP”
    ❌ “Please just work for once.”
    ❌ “WHY YOU NO WORK!”
    ❌

    View Slide

14. View Slide

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.
    

    View Slide

16. View Slide

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
    

    View Slide

18. View Slide

19. View Slide

20. View Slide

21. View Slide

22. View Slide

23. View Slide

24. View Slide

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
    

    View Slide

26. /CARMENCHUNG
    THANK YOU
    @CARMENHCHUNG
    WWW.CARMENHCHUNG.COM
    HTTP://BIT.LY/SAMPLE-PR-TEMPLATE
    

    View Slide