Jon Pretty

Either commit to keeping documentation rigorously up to date, or save yourself the effort to write it. With code it's easy: keep the documentation in the same repository as your code and make documentation an integral part of the review process.

I would actually suggest the opposite: keep documentation in a different repository so that it's easier to update at any time. Documentation almost always follows code, so when it's in the same repo, it's difficult to hold up a release because the docs aren't ready.

I believe that having atomic commits that bind together production code, testing code and documentation (along with other necessary artifacts—e.g. deployment scripts) is the only way to keep documentation up to date. If the docs are outdated, they'll cause a bad user experience.