I’ve been switching from Vim to Helix recently. I did the built-in tutor, and whenever I need to configure something, I look it up in the docs. The problem is, I only find what I already know to look for. Without reading the documentation more broadly, I don’t really know what I can configure in the first place.
So I’m curious, do you sit down and read documentation to understand a tool, or do you just search it when you hit a specific problem?
Depends on the docs but if they’re written well you’re best served by reading them in full. Rftm before looking at best practices and tips.
Problem is a lot of people don’t understand how to read a doc. There’s a terminology, phraseology, syntax. I have so many instances of people who say they didn’t see the answer in the docs and then you look and it’s right there. But the human mind tends to discard info it doesn’t understand how to process.
If you think you know how the Internet works but haven’t read the RFCs you might not know as much as you think you do. Read pretty much every one on ipv6 because the second hand resources are absolutely garbage.
Yes, but I am also of the opinion that not one single acronym should be used without at least once in the section saying what the acronym is. Many many programing docs with say what am acronym is exactly once, somewhere in the docs, and then never again.
Also, if there are more complex concepts that they use that they don’t explain, a link to a good explanation of what it is (so one doesn’t have to sift through mountains of crap to find out what the hell it does). Archwiki docs do this very well. Every page is literally full of links so you can almost always brush up on the concepts if you are unfamiliar.
There seem to be 10 extremely low quality, badly written, low effort docs for every 1 good documentation center out there. It is hard to RTFM when the manual skips 90% of the library and gives an auto-generated api reference with no or cryptic explanations on parameters, for example.
This reminds me of the ExifTool documentation… It feels like a well written documentation (and probably is) but the lack of context as a non programer can be overwhelming ://.
Thankfully, the forum was of great help and the maintainer is still active after all these years… Incredible tool by the way !!!