> The only thing worse than no documentation is incorrect documentation," he said. "Because no documentation means I go somewhere else to look for it. Incorrect documentation wastes my time."
Basically: yes. Some here on HN will disagree, but they are IMO wrong. Another big time-waster for users is failing to write a document intro that identifies the target audience and the document's target information goals; it sucks to get 30 pages into the document before you finally manage to figure out that it's not the document you want/need.
I don't agree. Bad documentation is worse than no documentation. At least with no documentation, I start with the expectation that I have to figure everything out on my own.
> Unless they are not reading it, or properly paying attention. [...] Sometimes it is on the user.
If they make no effort, sure. But looking for an answer to a question and finding something that seems to works is a perfectly reasonable way to use documentation. If there's a dangerous gotcha and it isn't documented right there, then the documentation is structured badly.
> Or following an unofficial document
That could be a very clear symptom of bad documentation.
Sometimes it's on the user, but if lots of users are failing to use your documentation, maybe consider that the documentation is bad.
Well, in their defense, most documentation is terrible. You get used to being able to find something in two Google searches that you couldn't find in five minutes looking through the docs.
Agreed on your last paragraph. One of my mantras to coders, as a tech documentarian, was that "Incorrect documentation is worse than no documentation".
It could also mean that they fall under the other extreme of perpetually outdated over-documentation. IMO the only thing worse than no docs are wrong docs.
> Your attitude of "docs are useless" is self-fulfilling.
Yes. Of course the docs are horrible, if no one can take time to improve them, because improving them is not "real work". Spending one day fixing the wiki pages to make information easy to find, that's one wasted man-day! On the other hand, the whole team spending a few hours in meetings to clarify misunderstandings that would not happen if there was one clearly written wiki page about the topic... that's okay, because communication is important.
I think another problem is that things work bad by default whenever the "customer" is not in a position to give feedback and require improvement. Suppose the developer needs an information, and the wiki page is hard to understand. The developer is hardly in a position to request a rewrite from the author -- the author has more knowledge (about given topic) and therefore is in a stronger position. Also, the author may choose to explain verbally or in e-mail, and then the wiki remains unfixed.
>Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it.
Maybe FOSS, but there is plenty of corporate SaaS and desktop apps that have basically zero documentation and you are told to contact the "support team" if you can't figure something out.
I'd argue that there's far too much documentation for documentation sake... nobody wants to spend valuable time updating a document that nobody looks at.
Basically: yes. Some here on HN will disagree, but they are IMO wrong. Another big time-waster for users is failing to write a document intro that identifies the target audience and the document's target information goals; it sucks to get 30 pages into the document before you finally manage to figure out that it's not the document you want/need.
reply