3 ms·
> Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed. Why does this work with Git but not wit
by robertlagrant 3y ago
> Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed.
Why does this work with Git but not with non-Git? Being in Git doesn't seem to relevant to raising documentation bugs as bugs.
- simonw 3y agoThe main reason is that if it's in Git you can enforce this policy through your PR process. There are a bunch of other reasons to keep documentation in git. The most important is that it gives you versioned documentation that matches your releases - if someone is running v2.3 of your software they can browse the documentation for that exact version using that tag on GitHub. If your documentation lives in some other system it can only ever attempt to be accurate for whatever the most recent release is. This is bad for people running older versions, and also makes it harder to develop documentation for unreleased code in a way that isn't potentially confusing.
- robertlagrant 3y agoUnderstood; I'm particularly talking about using bugs rather than making sure things are ready in PRs.
- cdchn 3y agoThe common logic seems to be that if your documentation is close to the code you're more likely to see that documentation exists and needs to be updated? I think it just boils down to "you must make time to update documentation" and make a process for it, rather than acting like "put your code in git" is some kind of panacea.