One of the critique most vocal opposition of code comments use online, is that code comments become outdated and thus harmful. Code comments are a great way to store very specific information of functions, hacks and decisions that gets lost over time. We often talk about documentation in two forms: either code comments that live with the code or readmes, API docs and other more curated written documentation. But both of them suffer from lack of history. But there’s more! We often look back at decisions without having the understanding and knowledge of that moment and critize the code or decisions made hastily. But almost always, decisions are made using the best understanding and knowledge (and restrictions of reality) of that particular moment in time. In this talk, I’ll explore how you can use issue tracker tickets, git commits and pull requests as a contemporary documentation: something that tells us about the world as it was when decisions were made and that doesn’t change as the project moves on. -- This version of the talk was given in TampereJS on September 5th, 2019

1. CONTEMPORARY DOCUMENTATION
TampereJS • Juha-Matti Santala • September 5th 2019

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

3. HI, I’M JUHIS
Developer Community & Web Dev @ Futurice
Founder of Turku <3 Frontend
Background in startups & consulting
@hamatti in Twitter
from Helsinki, !
@hamattiTampereJS

4. @hamatti
TEAMS CHANGE
TampereJS

5. DOCUMENTATION SHOULD
@hamatti
PROVIDE CONTEXT
TampereJS

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

7. COMMIT
MESSAGES
@hamatti
CODE
REVIEW
STORIES &
TASKS
3 BRANCHES
TampereJS

8. @hamatti
It’s hard because
the reward
comes later
TampereJS

9. COMMIT MESSAGE
@hamattiTampereJS

10. @hamattiTampereJS
https://xkcd.com/1296/

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

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

13. @hamattihttps: //chris.beams.io/posts/git-commit/TampereJS

14. CODE REVIEW
@hamattiTampereJS

15. https://github.com/facebook/react/pull/16302

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

17. STORIES & TASKS
@hamattiTampereJS

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

19. WRITE IT DOWN
@hamattiTampereJS

20. @hamattiTampereJS

21. @hamattiTampereJS

22. @hamattiTampereJS

23. @hamattiTampereJS

24. @hamattiTampereJS

25. @hamattiTampereJS

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

27. @hamattiTampereJS
twitch.tv/hamatti
Django + React
28th September 2019
OPEN SOURCE
IN TWITCH

28. @hamattiTampereJS
Dev Breakfast - newsletter for software developers
Sign up @
hello.futurice.com/dev-breakfast

29. THANK YOU!
@hamatti
@hamatti
https://hamatti.org
https://tammerforce.com
juhis@futurice.com
(PS. We are hiring!)
TampereJS