3 ms·
One of the reasons everyone hates writing documentation is precisely because nobody reads them. So this becomes a question of whether the time "wasted" writing
by Dalewyn 3y ago
One of the reasons everyone hates writing documentation is precisely because nobody reads them.
So this becomes a question of whether the time "wasted" writing documentation is cheaper than wasting time answering the same question again and again and again and again and again.
- capableweb 3y agoI guess that's true. I also guess one should consider the fact that you could (as long as things don't change) "waste" your time writing the documentation once, and saved time accumulates, while "saving" your time today not writing documentation will accumulate time spent on answering questions over and over. Saved time today VS saved time tomorrow, the constant question for startups :)
- williamdclt 3y agoeven if people ask the same question rather than looking for docs, it's still a huge timesaver to direct them to the documentation rather than re-explaining from scratch everytime. Plus, after having been shown the docs they _might_ now be aware that they exist and self-serve the next time
- dizhn 3y agoPlus it's an opportunity to fix the documentation. You will figure out quickly if a section of it is too confusing. It would also help you to realize if it's not easily discoverable.
- Spivak 3y agoMost servers have a bot that people use to store and retrieve common answers so contributors don't have to type it out every time. Now you could be like clearly that should just be in the web documentation but people still show up and ask even when it is and RTFM isn't exactly nice.
- simonw 3y agoIf nobody reads documentation, it means they don't trust it. Trust is something that documentation for a project has to earn over time. People will assume the documentation is incomplete and out-of-date, because that's the default for most things. If it's comprehensive and stays up-to-date with new changes, the project community will eventually come to realize they and start trusting it. But it takes time to build up that track record!
- deleted 3y ago[deleted]
- palata 3y agoI think we also tend to teach people to not read documentation (or spend time learning anything, really). Maybe there is some kind of negative reinforcement, too. The way it feels to me is: "I won't write documentation, because users don't read it -> Oh great, I will use ChatGPT to support my users -> The users don't know how to read documentation (or anything other than a 500-letters answer to a chat question) because they do everything with ChatGPT-like prompts -> I won't write documentation, because users don't read it". Same for many things: most people tend to complain about CMake, but almost every time, I quickly realize that they don't know how to use CMake. Either they complain about it and never used it, or they complain and use it wrong. Therefore many devs try to build alternatives that will solve that problem by "being better than CMake". Turns out I have seen Meson projects that were a big mess, it's not just a CMake thing. On the other hand, people who learn how to use Autotool/CMake/Meson usually manage to make it quite maintainable. Here the negative reinforcement would be: "People don't learn how to use the tools properly -> They make a mess -> They complain about the tool -> Someone makes a "better tool" -> People don't learn the new tool and make a mess -> repeat. I truly believe that we could solve many problems by teaching people how to learn, instead of building technology that helps them being productive without learning.
- rcxdude 3y agoCMake has a bit of a documentation problem, though. Firstly because the tool really was pretty bad at the start and the correct way to use it is the new way, but all the examples people run into in the wild are generally using it wrong, and this becomes self-perpetuating. The second issue is that the main documentation is actually really light on examples, it's just a fairly dry (and not always helpful) description of each part of it. I know there's some pretty good books but that isn't the kind of resource a lot of people are going to use when learning a tool, especially a tool they regard as secondary to their actual goal.
- reaperducer 3y agoIf nobody reads the documentation, that's an indication of success, not failure. It means you've done a good job with the product and people don't need help to use it.
- zokier 3y agoI find this prevalent attitude actually harmful. It is kinda weird thing to think that the tools we use should not need any learning or training, that anyone should just be able to pick them up and be productive. Of course I understand it is reflective of the current situation where naturally it is not worth seeking expertise when software gets at minumum a redesign every six months if not thrown out completely. But I'd really question is that actually good situation to be in?
- the_gipsy 3y agoYes, but don't confuse cause and effect.
- deleted 3y ago[deleted]
- esafak 3y agoThat is one of the explanations but you should not dismiss the others.
- nerdponx 3y ago1. Of course people read it. 2. People read the docs when you send them a link to the relevant doc page. Having docs makes your chat support a matter of linking to the right page.
- mrweasel 3y agoPeople read the documentation and fails to understand it. Writing good clear documentation that successfully guides your users or customers to gain the most value from your product is incredibly hard. It's fine to have Discord, or something similar, for when you users come to you with a problem, but then you need to consider if you have to go back at update the documentation. Early in my career hanging out on mailinglists was much more popular, frequently you'd ask a question and the maintainers of whatever software you where using would take the answer and put them into the regular FAQ or documentation. Now we replaced Discord with mailinglists and that might be sensible, the feedback loop just should not be excluded. Discord is terrible place to store knowledge.
- j0057 3y agoIf it's hard to write documentation that people will comprehend, doesn't that make it equally hard to write near real-time chat messages that people will understand?
- mrweasel 3y agoYes and no, but at least they'll be able to provide real-time feedback and you can tailor your response to they specific situation.
- sowbug 3y agoThat is survivorship bias. You hear only from the customers who don't read it. (I like writing documentation.)