Ask HN: How to RTFM?

I’ve had the opposite experience. I’ve found countless times that online tutorials confuse the issue, even if they help you to accomplish some specific task. The FM on the other hand tells it like it is. The trick is to only read the parts that you need to in order to clear up your confusion. This sometimes means reading one section and having to look something up in another section before you can understand the first, and this can sometimes be a recursive process, but if you have any understanding of the technology at all the recursion depth is rarely greater than two or three. You’ll quickly find that the things you don’t understand have straightforward explanations in terms of the things you do understand.

If you find yourself five levels deep in this process and still unable to comprehend what you’re reading, you need to take a step back and ask yourself if you do in fact have any real understanding of the technology you’re using.

Maybe a slow walk through each item in that subject is needed? Also for any particular popular subject there's more than one 'manual'.

I rarely read manuals. Except for roleplaying ones back in the day.

Is it a matter of time to focus for a long time on one task?

I feel that Google's manuals are notoriously bad or written in some kind of manualese dialect that only Googlers use. Things like Android or Firebase.

For Android, the unofficial manuals are better, or even Stack Overflow.

I've seen some very well written manuals though. Facebook seems to be good at it at least.

>if someone actually reads the manual

Uh, I thought everyone does.

>I don't see how manuals can be useful in the real sense

I'm...not sure how you can say this. Maybe you mean, reading a manual cover-to-cover. I don't think "RTFM" means that. Don't read the whole thing if it's boring! But I find once I'm well into using/learning some piece of software, and want to know everything, reading the entire manual is fascinating. Plus they vary in quality and readability. The python docs are extremely readable..aren't they? (especially if you have a high tolerance for Monty Python gags). Man pages mostly suck for learning software the first time, but are brilliant for refreshing the memory. Mostly, I google lists of the best books on a subject, and read as many of them as I can get my hands on. If I'm not enjoying one, I turn to another.

Exactly. The question is where's TFM today ? Doxigen is not TFM. The examples are not TFM. The comments are not TFM. The video posted on Youtube is not TFM. The blog is not TFM. I want TFM or at least TF Man Pages.

I print it and read it from cover to cover. I usually skip the preface, table of contents and index though.

I think reading software manuals is a waste of time. Unless if you do something wrong, you break something, it is much more efficient to just try to do a few examples and work with the tool, then when you need the manual, you read it. Just search on it what you need.

I think it is impossible to read those things and still be ahead of the curve on what is happening with software and things in general. Very time inefficient way of learning things. Try to learn by practicing and knowing where to search when problems happens, learn how to debug problems in real life effectively, because that's what you will do on your whole career.

I refer to documentation when I need to learn how to do individual things, and then once I'm starting to become comfortable with the library/software/whatever then I'll sit down in more depth and read through more of the documentation. At that point you have enough context to understand what's going on.

It's pretty simple with modern tools. For example, I'm learning Angular at the moment. I needed to learn how to use an IF statement in the HTML code.

The first google result is a blog post [1] from some guy. It's helpful, but really dilutes the core material. So instead I just went directly to the angular docs [2]. This was straightforward and gave me the info I needed to know.

Now CLI manuals from tools created in the 80's and 90's? Those are trickier. I'm still trying to learn a good way to grok those tools, but so far blog posts and Stack Overflow have been better than the man files, in my experience.

[1] https://toddmotto.com/angular-ngif-else-then

[2] https://angular.io/api/common/NgIf

I find the most detailed manual I can find on a thing and then I skim it, making note of chapter and paragraph headings.

90% of the benefit of a manual is knowing that a thing is possible the other 10% is the manual telling you how that thing is possible.

I do the same thing with man pages, I just scan down them, I don't care about the minutiae at that point but it's handy to know.

> Ask HN: How to RTFM?

(blinks)

Open to page one. Engage eyes. Parse words.

Read the documentation for what you're currently using and struggling with. Sometimes I peruse the documentation and discover new things I have never tried that I can try to make my life easier. It's a bit hard at first, but once you're used to it you can just read documentation and get work done. I also read the underlying source sometimes to get further insight.

I find that after you've picked up the basics, reference materials are usually the most useful part of documentation by far.

For programming languages I always add the standard library reference into my browser's search engines. For example, I can type "kt mutablelist" into my address bar to go straight to https://kotlinlang.org/docs/reference/?q=mutablelist&p=0.

Every time someone says 'read the manual', I weep for humanity.

When I open most manuals pages I may as well be reading 'ᐅᒥᐊᕐᔫᑉ ᐳᓪᓕᓕᒫᐸᒐ ᑕᑦᑕᕐᓂᖅ ᐊᒻᒪᔭᖅ'

It does nothing for me. I am seldom any smarter afterward.

These people don't understand there are different brain types, and only ~25% are read/write brain types.

Couple that with the fact that many in technology write in a broken, sterile form of English that any grammar correctly immediately flags as wrong.

No, the 'RTFM manual' people are typically extremely left-brained, analytical, black/white people who have no ability to see from others' point of, and often little desire to do so.

</endRant>

Documentation is good when it's good, bad when it's not. And people don't put much effort into documentation, in the average case. The final source of truth is the code. If you're wondering why something doesn't work, the code will tell you exactly why, because that is what controls success or failure. The manual author may have forgotten something, or the documentation might be out of date. You'll never know for sure.

For that reason, I would say that the amount of time I spend reading documentation is significantly less than then amount of time I spend reading the code.

For documentation authors, I'd recommend focusing on giving the reader the high-level context necessary to understand the code. It can be hard to dive into that. But things like "an error will be returned if these 86 conditions are true" probably should be a reference to the code, because you know there are going to be 87 conditions tomorrow and you'll forget to update the documentation.

As for your actual question, it can be hit and miss as to whether or not you can go into depth in something by merely reading. I have not found a book about modern Javascript ("use the axios library to make HTTP requests from your code") and just have to cobble things together from existing code, googling for the current problem I'm having, etc. I imagine that sucks for people new to the field, but I suppose is why you get paid for having experience. For things like SQL, you can definitely find a book about it, as it's been essentially the same for my entire life, and what really matter are the fundamentals of relational databases... the Postgres-specific things you will probably discover while doing some work.

So I guess what I'm saying is... focus on getting experience. If you tell yourself, "I want to write 'foo' in Javascript" you will learn Javascript somehow. It's not as easy as just reading something, but it will stick with you forever. And when you run into the inevitable obscure error message, realize that you can just read the code to figure out what's actually happening. You need not be dependent on a secondary source when reading the primary source works. Because someday, you will be paid to work on code without documentation, and you will need that skill.

Don't worry about memorizing the manual. When I first got into programming, focusing on Ruby, I would study the Ruby docs intensely. I got really good at understanding the standard library. I read the heck out of the manual, and in interviews that focused on how well I knew Ruby, I sounded really experienced. But I struggled to build basic things.

There's a bunch of different types of documentation, and being able to skim them enough to get a basic understanding is super helpful! A non-comprehensive list of different types of documentation includes:

- man pages

- REST API docs

- Language docs

- RFCs

- Tool specific docs

Let's get specific.

- Say you need to find a way to filter text in a Bash shell, and you want to read the man page for grep. Maybe you want to read https://www.tldp.org/HOWTO/Man-Page/q3.html to start understanding this... 'grep [-abcdDEFGHhIiJLlmnOopqRSsUVvwxZ] [-A num] [-B num] [-C[num]] [-e pattern] [-f file] [--binary-files=value] [--color[=when]] [--colour[=when]] [--context[=num]] [--label] [--line-buffered] [--null] [pattern] [file ...]'

- Let's say you need to want to better understand how JSON works because you are working on a networking library. Maybe scanning https://www.json.org/ will help you read this https://tools.ietf.org/html/rfc8259.

- Let's say you're reading API docs for Artifactory, and they your not sure how REST works, but they keep talking about it. Maybe scanning https://en.wikipedia.org/wiki/Representational_state_transfe... will help you read https://www.jfrog.com/confluence/display/RTF/Artifactory+RES...

I identify with your pain. Reading docs is hard, especially when you're diving into unfamiliar problems with unfamiliar tools. All I can say is that you just keep pushing yourself to get better at it, and if you're lucky, maybe you'll be fortunate enough to work with people who can help make the learning curve less steep. There's no shortcut to getting to where you want to go.

A few tips & tricks that make things less painful for me:

- getting high level context by watching short YouTube videos makes it easier to read denser material that is hard to absorb

- working on things that interest me makes reading dry documentation a lot easier

- building something at the same time I'm reading docs makes it a lot easier to spot errors in the docs & gaps in my understanding

Keep pushing. It's always going to be hard. You just get better at working on hard things :)

Try things out as you read.

I read the Unix manual from cover to cover when I started out. As I went through it I'd try the commands. Often there were short examples.

This was when there were only a couple of hundred pages though.

Regarding the language -- usually it's not only too terse but badly written. However the classic books e.g. Kernighan & PIke's UNIX Programming Environment are excellent.

Don't read to remember everything (that's virtually impossible for most people), mostly skim to build an index of concepts and possibilities in your mind – and leave the details to the reference materials. Don't even bother to try and remember details for something you don't immediately need. Computers are good at details, humans are good at high-level webs of concepts.

You also need to be comfortable with stopping at a certain layer of abstraction and mostly trusting that abstraction holds. For many programmers (including me) I suspect that's the model of a computer presented by C. I don't really bother to try to understand much of what's underneath this model because time and my brain is regrettably finite. I just know more or less what it's meant to do and trust it works. (Trust that, as evidenced by Spectre/Meltdown, is unfortunately misplaced, but still – I'm only one person.)

If I had to attack trying to understand, say, PostgreSQL, I would find out what sort of thing it is (an RDMBS), what sort of ingredients that has (a network protocol, a query parser, fundamental data storage structures, etc) and fill in detail as my interest takes me. There's always going to be more to learn about – these are massive subjects – so it's always going to be piecemeal.

Manuals are not really for reading cover to cover. You generally want to use the table of contents, the index, or searching of some variety (google, ctrl-f, whatever) to narrow in on exactly what you want to know. A few scenarios I find them useful:

(1) If you're getting conflicting advice from blogs and stack overflow: this is often the case when software is changing fast. Manuals are often explicitly versioned to match the software, so if the manual covers the topic you care about, going to the latest manual is a great way of figuring out which advice is current.

(2) Skimming the index: a quick way of discovering topics you can then explore in more detail either in the manual itself or through follow up googling.

(3) A manual you know and love. Over time you get a feel for which manuals you interact with are good. If a manual is good and you've gotten comfortable reading it, it's often faster to find the answer you're looking for by searching the manual directly rather than wading through a google search.

Just so you know, manuals aren't read like story books, from beginning to end. They're arranged in a tree structure with the root/trunk giving a rough Overview or Introduction on whatever the manual is about, the branches explaining various features in broad terms and ordered by their importance, and the leaves explaining the most arcane details you might eventually need to know about.

What I do is first take note of whatever seems like a Table of Contents which neatly lays out this tree-like structure with one-line summaries. Pay attention to each title, remembering their existence for future reference, and determine how much you want to know from the get-go. Of course, the root/trunk, otherwise known as Overview or Introduction, will be relevant to everything so go over it. Only go to the deepest branches/leaves when you're planning on using that knowledge, but always go over the branches that lead to those leaves.

That about covers it. For example, there was recently a question on SE on what had higher precedence in the shell, the | or the &&. Had this person gone over the shell grammar section of the bash manpage, the answer would've been obvious:

> Pipelines: A pipeline is a sequence of one or more commands separated by one of the control operators | or |&.

> Lists: A list is a sequence of one or more pipelines separated by one of the operators ;, &, &&, or ||, and optionally terminated by one of ;, &, or <newline>.

By the way, some answers say that you shouldn't go over the manual unless you want to know a detail, but I think it sometimes pays off to read it whole (or most parts of it). I've read most of the manuals for vim, bash, i3, urxvt, among others, and I can say, it has paid off. This might depend on how you learn best, though.

As others have said, it is often helpful just to have a general idea of what things can be done so one can know where to look to find it. E.g. it might be “I know a library/tool related to this problem, let me find it’s manual and guess some keywords to search”, or even just “this feels like something for a lesser used unix tool, let me do info coreutils and look around.”

For programming languages, the thing I find particularly helpful is a formal grammar as it typically resolves any syntax related issues (and often these are subtle issues where two terms look similar written but one may be more restrictive than the other). The other thing I try to do is build a mental model of the compiler: If one has a good idea of what sort of thing one’s code might be compiled to, it is more obvious what constructs should and should not be allowed. This can backfire slightly: if one has an idea that eg Javascript will be compiled to fast code, it is obvious that the with construct should not be allowed, but maybe that just implies that the construct makes code slow.

I think this can help to understand eg why virtual methods are slower to call or why overloading works the way it does in an oo language, or eg why only certain subtyping operations should be around (in particular one way to decide this is “this language has certain typing rules and those demand certain constraints” Another is “this language wants to compile this construct to a certain thing and that requires that certain obvious constraints must follow”

Manuals complement books and tutorials. Say I'd like to review sockets: I'd probably first pull up Beej's Guide to Network Programming [1], and then switch over to (say) 'man 2 listen' when I want to dive in and see for myself that Beej's exposition is true on my system. :-) Then I'd dive in and try it out in code, referring back to the man pages as needed.

[1] https://beej.us/guide/bgnet/html/multi/index.html

Seems like you're going about it backwards - start with the reference docs to figure out how something _should_ work, then if that breaks down start looking to other sources for workarounds or more information. This approach will force you to get better at understanding TFM. Going to SO or blogs may be a quick way to get a solution but as a software engineer you also need to understand how and why that solution works, which is where the reference docs come in.

If you're finding that TFM is just too dense to get through then you probably need to start learning/understanding the building blocks in whatever way works best for you (online courses, wikipedia, more reference manuals, tutorials, etc).

I find example usages first then decipher what the manual means while referring to them. Many times it feels like manuals have their own language, phrasing, templating syntax or what-have-you. If you have something to compare against when they you can usually understand what they mean from that. I really wish more manuals had simple examples at the start of the manual. You don't even need many, just like 2.