Contemporary Documentation

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 contemporal 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.