Synthesize David Thompson | My Favourite Git Commit
- Documentation is good when, and only when, it is also discoverable
- Your documentation is discoverable when it exists where your audience goes when they are looking for it
- Commit messages often not indexed in search engines (external or internal)
- Agree with “most” that including the raw error message is fantastic; increases precise searchability
- The commit message referenced in “most” is fantastic documentation (agree with all points made); however, it isn’t as discoverable as it could be.
- Better to write the documentation in a more accessible place and link to it (or even copy/paste it so long as you also include the link) in the commit message
- Agree with “least” that commit messages are not the most discoverable place
- Agree with “least” that tests are (S-tier) documentation
- (“Readme Driven Development” n.d.)
“Readme Driven Development.” n.d. Accessed February 14, 2022. https://tom.preston-werner.com/2010/08/23/readme-driven-development.html.