Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Contemporary Documentation - TampereJS

56 views

Published on

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

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Contemporary Documentation - TampereJS

  1. 1. CONTEMPORARY DOCUMENTATION TampereJS • Juha-Matti Santala • September 5th 2019
  2. 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. 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. 4. @hamatti TEAMS CHANGE TampereJS
  5. 5. DOCUMENTATION SHOULD @hamatti PROVIDE CONTEXT TampereJS
  6. 6. (MOST OF THE) DOCUMENTATION IS A LIVING ORGANISM @hamatti (README, API DOCS, CODE COMMENTS) TampereJS
  7. 7. COMMIT MESSAGES @hamatti CODE REVIEW STORIES &
 TASKS 3 BRANCHES TampereJS
  8. 8. @hamatti It’s hard because the reward comes later TampereJS
  9. 9. COMMIT MESSAGE @hamattiTampereJS
  10. 10. @hamattiTampereJS https://xkcd.com/1296/
  11. 11. @hamatti “What would you like to know two years from now?” TampereJS
  12. 12. @hamatti “What would you ask from a colleague who wrote this two years ago?” TampereJS
  13. 13. @hamattihttps: //chris.beams.io/posts/git-commit/TampereJS
  14. 14. CODE REVIEW @hamattiTampereJS
  15. 15. https://github.com/facebook/react/pull/16302
  16. 16. WRITE IT DOWN @hamatti ASK A LOT OF QUESTIONS DON’T DELETE COMMENTS TampereJS
  17. 17. STORIES & TASKS @hamattiTampereJS
  18. 18. STORIES & TASKS @hamatti Origin / Business Driver How to reproduce? Definition of Done Clarifying questions TampereJS
  19. 19. WRITE IT DOWN @hamattiTampereJS
  20. 20. @hamattiTampereJS
  21. 21. @hamattiTampereJS
  22. 22. @hamattiTampereJS
  23. 23. @hamattiTampereJS
  24. 24. @hamattiTampereJS
  25. 25. @hamattiTampereJS
  26. 26. RECAP @hamattiTampereJS COMMIT MSG, CODE REVIEW & ISSUES “WHAT WOULD I WANT TO KNOW IN 2 YEARS” WRITE IT DOWN
  27. 27. @hamattiTampereJS twitch.tv/hamatti Django + React
 28th September 2019 OPEN SOURCE IN TWITCH
  28. 28. @hamattiTampereJS Dev Breakfast - newsletter for software developers Sign up @ hello.futurice.com/dev-breakfast
  29. 29. THANK YOU! @hamatti @hamatti https://hamatti.org https://tammerforce.com juhis@futurice.com (PS. We are hiring!) TampereJS

×