Documentation Writing (for coders)

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