Documentation
Writing
(for coders)
Carmen Chung
@carmenhchung
Slide 2
Slide 2 text
Types of
documentation
Code comments.
Commit messages.
Pull Request descriptions.
How To/Reference Guides.
Blog posts.
@carmenhchung
Slide 3
Slide 3 text
@carmenhchung
Slide 4
Slide 4 text
No content
Slide 5
Slide 5 text
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
Commit
messages
CLARITY & BREVITY
✅ Write short, clear commit messages.
❌ “WIP WIP WIP WIP WIP”
❌ “Please just work for once.”
@carmenhchung
Slide 11
Slide 11 text
Commit
messages
CLARITY & BREVITY
✅ Write short, clear commit messages.
❌ “WIP WIP WIP WIP WIP”
❌ “Please just work for once.”
❌ “WHY YOU NO WORK!”
@carmenhchung
Slide 12
Slide 12 text
Commit
messages
CLARITY & BREVITY
✅ Write short, clear commit messages.
❌ “WIP WIP WIP WIP WIP”
❌ “Please just work for once.”
❌ “WHY YOU NO WORK!”
❌
Slide 13
Slide 13 text
Commit
messages
CLARITY & BREVITY
✅ Write short, clear commit messages.
❌ “WIP WIP WIP WIP WIP”
❌ “Please just work for once.”
❌ “WHY YOU NO WORK!”
❌
Slide 14
Slide 14 text
No content
Slide 15
Slide 15 text
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.
Slide 16
Slide 16 text
No content
Slide 17
Slide 17 text
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
Slide 18
Slide 18 text
No content
Slide 19
Slide 19 text
No content
Slide 20
Slide 20 text
No content
Slide 21
Slide 21 text
No content
Slide 22
Slide 22 text
No content
Slide 23
Slide 23 text
No content
Slide 24
Slide 24 text
No content
Slide 25
Slide 25 text
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
Slide 26
Slide 26 text
/CARMENCHUNG
THANK YOU
@CARMENHCHUNG
WWW.CARMENHCHUNG.COM
HTTP://BIT.LY/SAMPLE-PR-TEMPLATE