3 ms·
> Some things might not be possible to fix. Teaching people to RTFM, for instance. No search engine will be able to replace consistent and comprehensive documen
by Swizec 12y ago
> Some things might not be possible to fix. Teaching people to RTFM, for instance. No search engine will be able to replace consistent and comprehensive documentation written by the people who know the system intimately, but it's hard to convince most users, many developers, even, that this is actually worth the effort it takes, both to read and write.
People will RTFM if it isn't boring, dry, and useless.
There's a fine balance to be struck between nice-to-read prose and giving people exactly what they need, quickly enough for them to actually read your stuff. But the thing is, if your documentation is difficult to read and doesn't flow well, it might as well not have been written. Everybody will give up before they learn.
And vice-versa, if your documentation is TOO nice to read and does too much hand-holding. People will gloss it over and miss important details.
Teaching is hard. Much harder than people give it credit.
And because there are no unicorns who can both intimiately understand the system and be good at documenting it, you should do the next best thing - have a person with enough technical background to be able to talk to the experts, but is also good at writing about it write your docs.
This seems to be the approach taken by most self-published tech writers these days. They're good enough to understand the system, but also decent enough at writing about it.
- agumonkey 12y agoI really RTFM when back against the wall, otherwise I only SkimTFM. I wish embedded manuals, instead of disconnected words, having a REPL, a failing test suite to see how the pieces work together. Brett Victor style. Maybe it's an overly lazy desire, and nothing will replace the fact that you're willing to focus on reading what people wanted to express about a program. Also, embedded/repl would avoid outdated documentation drift.