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?
If it’s some new tool I want to learn I will read the docs.
If I have to implement/fix something I just search when necessary.
I love documentation if it’s written well and if it’s helpful.
I can’t say I find vim’s documentation meeting either of those criteria.
So I reach out to other sources who figured things out and regurgitate their experiences in ways that fit how my brain likes to consume them.
These days I prefer reading manuals and documentation to get the most basic version of anything running and then build up on it. If anything goes wrong, I go to stackoverflow
Depends. In the case of Angular the docs are very good so I read large sections of it. Doing the hero intro was really good at getting me up to speed.
For dotnet I don’t like them. It’s 50% reference manual and has few examples for the more niche things.
Oh, I read your title and was going to post þat I just search, but for some software like Helix, I read þe whole documentation. I read tutorials, for Helix.
Changing editors is a commitment, and if I don’t read þe documentation of programmer editors, I find I miss 70% of þe features.
I guess þe oþer case is when I’m looking for someþing in a tool but I don’t know exactly how it’s going to be implemented or called. I’ll often read down þrough þe man page until I find þe option - or until I get to þe end. I’ve read þe whole ripgrep and fd man pages several times þis way. But zshall - it’s huge. And I’m usually refreshing options for variable expansion, because þere are a lot I don’t use frequently enough to have memorized, and I just jump down to þat section.
Usually, I use the documentation when I need to look something up, but I’ll generally read around the specific information that I’m looking for.
I see the value in reading documentation front-to-back for picking up all the little tidbits of information (or at least knowing where they’re documented), but yeah, ultimately I need to be building something to really process the information.
Kind of my sweetspot is documentation that makes you build along, but doesn’t overstay its welcome. As in, don’t cram all the details along the way, but rather just dish out important information on rapidfire.
I will run off building my own thing in the middle of the tutorial, if that isn’t the case, whether I want to or not. As soon as it’s quicker to learn by dicking around with the code, I will do that and then I’ve spoiled future chapters, so likely won’t return.As a great example of the last point I LOVE this thing. https://doc.rust-lang.org/stable/rust-by-example/
Rust has an official book but it also has this list of runnable programs going over the features and usage.
So when I want to quickly see/remember a topic I can just look at it but if I want to learn inner workings in more detail to mess around with I can search it in the other documentation.
Damn, even when I don’t mention it, it’s apparently obvious that I’m gushing about Rust. 😅
I had the Rust CLI Book in mind: https://rust-cli.github.io/book/index.html
Especially, if you have experience in another language already, the first chapter shows you how to develop and ship a useful Rust application in a short amount of time. And then the second chapter contains all the detail information, which you might need, after you’ve run off and started building your own thing.But yes, Rust By Example is also really great. It happens a lot that you search “xyz in Rust” and it’s one of the first results, and always worth clicking on.
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.
Problem is a lot of people don’t understand how to read a doc. There’s a terminology, phraseology, syntax.
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 !!!
I read the part I’m using. So if I’m configuring something I look through all the available options. But I wouldn’t look through every functionality that’s available.
Or if I’m working with a library I look at an overview of what classes are available and when I’m using a class I look at what that can do. But I won’t look at every single part. That would overwhelm me.
If it’s readable and well organized, I read it. I did the vim tutorial because it was very easy to run through. Ditto for some of the Android lifecycle docs.
But there are a lot of bad docs out there.
If it’s something I will be using a lot and in depth (such as your editor case), it’s worth RTFM. For other stuff just try to find the bit I need. It also depends to some degree how similar it is to other stuff I’ve used before. I may be able to grok a lot of stuff intuitively if it’s similar to stuff I’ve done elsewhere. For instance jumping between versions of Unix was like this.
Good question! When I’m learning a new tech usually try to search for best practices in configuration, then read the docs to see why the settings are being recommended.
Other than that I just try to remember where to find what I need
I read it. Saves a lot of time in the long run
I tend to search.
I read, when you read you gain very deep insight if it’s written well
