Documenting decisions alongside code with cross-referencing

Where to document design decisions in a code base may not always be a straightforward decision! Especially when the relevant code is scattered across the codebase.

tagref is an open source tool provides a simple system for cross referencing notes and code and making sure that they to go out of data (to a great extent). It’s inspired by the “Notes system” used in the development of Glassgow Haskell Compiler (GHC).

This short lighting talk will cover the problem, idea that the tool is based on, what tagref, the tool itself actually is and show examples.

Disclosure: I am not the author of tagref but I’ve contributed a few patches.

How you can write and maintain design decisions in documents (markdown etc.) while making sure they don’t go out of date.