Hacker News Reader

Comment by x87678r | Hacker News Reader

I've seen a lot of people waste time on writing documents that just sit there unread. No one wants to RTFM, esp one written a few years ago that is likely not accurate.

View on HN

documentation has to be actively maintained, but even old and innacurate documentation can serve as a starting point (and be update to be accurate) when something needs to be investigated/refactored etc

without any documentation, all you have is word of mouth, and when people quit, the organizations knowledge DECREASES over time

> people waste time on writing documents that just sit there unread. No one wants to RTFM

documentation is hard... most documents that i have seen are mostly brain dumps, very badly formatted, just very hard to follow...

one thing i think severely missing in school and otj training is how to write documents people WANT to read

The most valuable thing in software is knowledge. That comes either from experience (slow and painful, the jagged little pill), from other people (if you're lucky enough to have a local expert, I often don't) and from books/docs (easily available, if a little time-consuming to read). I go straight for the docs. They give the biggest ROI I can easily get my hands on. Really knowing your tools gives you a lot of power and it's a shame people don't seem willing to spend time on them.

I think there's value in docs from a level setting perspective...it's usually way quicker to talk someone through what's changed since the last update than from scratch.

Then that's poor documentation.

Documentation, like comments, is most useful when it answers "why" sometimes "how" but rarely "what". And "why" changes much more slowly.

It's why I find API documentation to border on useless. I need examples and rationale, not variable names.

Reply on news.ycombinator.com