$30 off During Our Annual Pro Sale. View Details »

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.

Carmen Chung

May 15, 2020
Tweet

More Decks by Carmen Chung

Other Decks in Education

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