Jon Pretty

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.

I think it would be nice, but too difficult to achieve. If a method is discovered to be buggy after release, there's no way to tell users that in the version of the documentation that's in that release. Documentation needs to evolve to be kept up-to-date...

Final point: if by policy you delay docs release, how are your users incentivized to keep up to date about your project (including it's bugs) with those.

It wouldn't be the policy to delay, so much as to avoid putting the pressure on having perfect docs at the point of release. It's trying to reduce the friction in writing documentation at any time.

You raised very good points. My concern, at the beginning, was finding a way to minimize the effort in enforcing the update of docs, as I believe they're a fantastic medium to minimize the friction to adoption and contribution. How would you deal with that?

Enforcing is harder (and hints at a need for a policy, as you suggest...) My goal is to make it easier to make contributions. For an OSS project, a separate docs repo can lower the barriers to contributing (think, closer to a wiki).

The docs repo could have much easier criteria on whether PRs are merged, and could have more owners with commit rights. With the Github online editor, it could take seconds to update the docs.