Live data from Hacker News

Ask HN: How to RTFM?

news.ycombinator.com

21–30 of 47 posts

Re: Ask HN: How to RTFM?

#21
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.

Re: Ask HN: How to RTFM?

#22
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 :)

Re: Ask HN: How to RTFM?

#23
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.

Re: Ask HN: How to RTFM?

#24
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.

Re: Ask HN: How to RTFM?

#25
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.

Re: Ask HN: How to RTFM?

#26

>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 fascina…

> > >if someone actually reads the manual > Uh, I thought everyone does. ... have ... have you ever met another programmer?

The old ones did this. Want to learn C? Read K&R. Want to learn Perl? Read the Camel book. Want to learn C++? Read Stroustrup. That was the way we learned.

These days? Not so much. Stroustrup is now big enough to use in self-defense. I'm not sure there ever was an equivalent book for Java. (There is one for Go, however.) React? Angular? TypeScript? Do they have authoritative books? If they do, is that the canonical way to learn them?

I think something changed 20 years ago. The book used to be the way to learn, and now it's not. I don't know if the programmers changed, or if the languages changed, or if the books changed, but something did.

Re: Ask HN: How to RTFM?

#27

>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 fascina…

> Uh, I thought everyone does.

I thought no-one does!

:-)

Re: Ask HN: How to RTFM?

#28
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 .

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.

Re: Ask HN: How to RTFM?

#29
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”

Re: Ask HN: How to RTFM?

#30
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

Post reply on HN