Encouraging a culture of written communication

Re:Encouraging a culture of written communication by simonw on Monday May 11, 2020 @01:57PM (#23144979)

I love keeping documentation in the same repo as the code, because you can enforce updates to the relevant documentation as part of the code review process. "This change is great - don't forget to update the docs in docs/blah.md before you land this pull request."

You can even write unit tests that verify that certain things are mentioned in the documentation: https://simonwillison.net/2018/Jul/28/documentation-unit-tes...

[ Parent | on HN ]

Re:Encouraging a culture of written communication by gen220 on Monday May 11, 2020 @02:50PM (#23145582)

Ooh thank you, unittesting the documentation is a great tip that I will steal.

Totally agree, code review is a huge plus for many reasons.

If your company/project has a build graph (bazel, pants etc), you can even make the source file a dependency of the document, so whenever the source file changes, it's trivial to generate an automated "hey don't forget to update <doc> if it's relevant to this change".

[ Parent | on HN ]