What I Read — coding in the open and telling stories

• David Thompson shares his favorite commit from his time on GOV.UK. The post has introduced me to the idea of coding in the open. Here is why he likes it:

  • explains the reason for the change
  • searchable
  • tells a story
  • makes everyone a little smarter
  • adds an extra bit of human context

• Joel Chippindale talks about telling stories through your commits. He tells that VCS is kept forever, always up to date and searchable.

  • git log --grep='Commit contents' search all the contents of all your commit messages
  • git log -S 'Diff contents' search all the contents of all the code changes
  • git blame where each line of code was last changed

  So, how do we make sure that this documentation tells a useful story?

  1. Make atomic commits minimum viable commit, avoid ‘and’ in commit messages
  2. Write good commit messages links to a place which explains more about the problem
  3. Revise your development history before sharing git rebase --interactive