2 ms·
> the only thing worse than no documentation is incorrect documentation. verify instructions work. i absolutely agree with the principle but i notice especiall
by rojobuffalo 4y ago
> the only thing worse than no documentation is incorrect documentation. verify instructions work.
i absolutely agree with the principle but i notice especially with internal projects that it is often not lived up to. once-valid docs become invalid over time. once you have the experience of getting bad information from a documentation project it loses credibility. readers ends up with extra work determining validity and communicating when changes are needed.
what does it look like when that problem is solved? i think of StackOverflow and DigitalOcean. they both have comment sections and date stamps. authors respond to comments. that's often how i figure out if something is still valid or not. it seems important that authors revisit or re-verify things they wrote. and if that's not something that is rewarded then it's not likely to happen.
- onionisafruit 4y agoThis worry causes me to write less documentation than I probably should. I tend to see every line of documentation as a liability because I need to track whether future changes changes will make the doc out of date. I would love some kind of dependency chart that goes from code to documentation where I can easily see what docs may need to be updated when I change a function.