My teammate recently wrote a blog post on how we document Why in git commits and PR descriptions.
https://medium.com/better-programming/daily-habits-to-turn-y...
Would also recommend checking out a related talk by a tech lead at StitchFix: https://confreaks.tv/videos/rubyconf2018-documentation-trade...