News for hackers. Stuff that matters.
Re:Ask HN: How do you organize software documentation at work? by robertlagrant on Wednesday February 14, 2024 @10:10AM (#39370632)
> 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.

Re:Ask HN: How do you organize software documentation at work? by simonw on Wednesday February 14, 2024 @10:57AM (#39371398)
The 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.

Re:Ask HN: How do you organize software documentation at work? by robertlagrant on Wednesday February 14, 2024 @04:15PM (#39375495)
Understood; I'm particularly talking about using bugs rather than making sure things are ready in PRs.
Re:Ask HN: How do you organize software documentation at work? by cdchn on Wednesday February 14, 2024 @02:38PM (#39374176)
The 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.