This document discusses the importance of documentation as a living organism with three branches: commit messages, code reviews, and stories & tasks. Effective documentation includes asking questions, writing details, and focusing on the needs of future readers by considering what would be helpful to know years later. Commit messages, code reviews, and documenting stories and tasks well helps provide valuable context for contemporary and future readers.

1. CONTEMPORARY DOCUMENTATION
PyAmsterdam • Juha-Matti Santala • March 10th 2021

2. CONTEMPORARY
/kənˈtɛm.pəˌɹɛɹ.i/
1. From the same time period,
coexistent in time.
2. Modern, of the present age
@hamatti
PyAmsterdam

3. CONTEMPORARY
/kənˈtɛm.pəˌɹɛɹ.i/
1. From the same time period,
coexistent in time.
2. Modern, of the present age
@hamatti
PyAmsterdam

4. HI, I’M JUHIS
Developer Advocate @ Futurice
Founder of Turku <3 Frontend
Background in startups & consulting
@hamatti in Twitter
from Helsinki, 🇫🇮
@hamatti
PyAmsterdam

5. @hamatti
TEAMS CHANGE
PyAmsterdam

6. DOCUMENTATION SHOULD
@hamatti
PROVIDE CONTEXT
PyAmsterdam

7. (MOST OF THE)
DOCUMENTATION
IS
A LIVING ORGANISM
@hamatti
(README, API DOCS, CODE
COMMENTS)
PyAmsterdam

8. @hamatti
3 BRANCHES
PyAmsterdam

9. COMMIT
MESSAGES
@hamatti
3 BRANCHES
PyAmsterdam

10. COMMIT
MESSAGES
@hamatti
CODE
REVIEW
3 BRANCHES
PyAmsterdam

11. COMMIT
MESSAGES
@hamatti
CODE
REVIEW
STORIES &
TASKS
3 BRANCHES
PyAmsterdam

12. @hamatti
It’s hard
because the
reward comes
later
PyAmsterdam

13. COMMIT MESSAGE
@hamatti
PyAmsterdam

14. @hamatti
https://xkcd.com/1296/
PyAmsterdam

15. @hamatti
“What would you
like to know two
years from now?”
PyAmsterdam

16. @hamatti
“What would you
ask from a
colleague who
wrote this two
years ago?”
PyAmsterdam

17. @hamatti
https:///dhwthompson.com/2019/my-favourite-git-commit
PyAmsterdam

18. CODE REVIEW
@hamatti
PyAmsterdam

19. @hamatti
PyAmsterdam

20. WRITE IT DOWN
@hamatti
PyAmsterdam

21. WRITE IT DOWN
@hamatti
ASK A LOT OF QUESTIONS
PyAmsterdam

22. WRITE IT DOWN
@hamatti
ASK A LOT OF QUESTIONS
DON’T DELETE COMMENTS
PyAmsterdam

23. STORIES & TASKS
@hamatti
PyAmsterdam

24. STORIES & TASKS
@hamatti
PyAmsterdam

25. STORIES & TASKS
@hamatti
Origin / Business Driver
PyAmsterdam

26. STORIES & TASKS
@hamatti
Origin / Business Driver
How to reproduce?
PyAmsterdam

27. STORIES & TASKS
@hamatti
Origin / Business Driver
How to reproduce?
Definition of Done
PyAmsterdam

28. STORIES & TASKS
@hamatti
Origin / Business Driver
How to reproduce?
Definition of Done
Clarifying questions
PyAmsterdam

29. WRITE IT DOWN
@hamatti
PyAmsterdam

30. DOCUMENTATION WORKFLOW
@hamatti
PyAmsterdam

31. @hamatti
PyAmsterdam

32. @hamatti
PyAmsterdam

33. @hamatti
PyAmsterdam

34. @hamatti
PyAmsterdam

35. @hamatti
PyAmsterdam

36. @hamatti
PyAmsterdam

37. @hamatti
PyAmsterdam

38. RECAP
@hamatti
PyAmsterdam

39. RECAP
@hamatti
COMMIT MSG, CODE REVIEW & ISSUES
PyAmsterdam

40. RECAP
@hamatti
COMMIT MSG, CODE REVIEW & ISSUES
“WHAT WOULD I WANT TO KNOW IN 2 YEARS”
PyAmsterdam

41. RECAP
@hamatti
COMMIT MSG, CODE REVIEW & ISSUES
“WHAT WOULD I WANT TO KNOW IN 2 YEARS”
WRITE IT DOWN
PyAmsterdam

42. THANK YOU!
@hamatti
@hamatti
https://hamatti.org
juhis@futurice.com
PS. I run a developer newsletter called
Dev Breakfast at
hello.futurice.com/dev-breakfast
PyAmsterdam