Ask HN: How to RTFM?

Thing is, Documentation that thorough is hard, and it's only harder with the rapid release schedules many have adopted as of late. Then you have software that hasn't had a completed set of man pages in years, because no one bothered to finish it. So, I've resorted to reading the source code to see what the blazes is going on if there's no competent manual available.

If I'm grabbing for the manual in the first place, I've found it's mostly to search for an answer to "Can I do x in y context without having to code it in the way I know works but is exhaustive, bloated, and a waste of my time".

I ran into this last year with an XML parsing library; I wanted to do something so simple yet the library appeared as if it couldn't - parse incoming XML payload - but the library's manual only discussed parsing XML as if it were fully formed and from a local file, which is only applicable in a fantasy world. It seemed very odd to me that the library would have its own routines for local file loading, so I assumed it was required and I would have to write incoming XML to a file and load it every time. Then I looked at the source code to the library and discovered the author had coded it specifically so that newbies could use it and not be affected by XXE attacks. Now the library specifically mentions this in its tutorial, but not in its manual, so I never saw the bloody thing.

I wasted a whole day for something that could have been mentioned in the "manual".

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.

I used to feel the same way... until I actually read one.

It was a point several years ago that I was looking for a "better" solution to something I was doing. A bunch of Stack Exchange answers on the topic each had a different way of doing it, and each was as complicated as my own solution. Over the course of years, people tried to make the solution better.

Then I noticed the very bottom answer, below some dozen others. Posted about a month before my search.

It was one line.

The individual just posted the one-line answer and a link to the manual.

It was part of the standard library.

And had been SINCE INCEPTION.

It was at that point that I began to RTFM. There are good manuals and there are bad manuals. But one thing I've noticed is that for most libraries, it is absolutely invaluable to be able to have a high level picture of what's available. It has completely changed the way I code, now.

First, read a few hello world tutorials so I can wrap my head around the gist. Then RTFM. Then maybe read a book about it if I want a good idea of best practices. Only then do I search SE or other online sources.

Which I now rarely have to do, for the things in which I RTFM...

The thing is with RTFM is that it takes time. We don't all have time. So while RTFM will sometimes help, almost all the manuals lack good examples. It would be much more useful if all manuals had an equally extensive examples section. Then we could say RTFE(xamples). `man awk` and `/` for `examples`, they have a great example section. `man curl` doesn't have a specific section but does have examples sprinkled throughout the options. `man kill` has zero references to `example`, yeah, probably don't need it but there are some nice `kill` tricks that could be in there.

I do read `man` pages daily, and it does get easier & faster with time. I am a pro at searching man pages, but again, most lack good, high quality examples, which would be most effective. As soon as I open a man page I press `/`, which lets me search. If I am looking for an option (e.g. -F) I search for ` -F` with the preceding space, this almost always gets you the actual option, not just mentions of it. Then I press `n` or `shift + n` to go to the next and previous results.

Also keep in mind that some apps don't have man pages, for those try `help ` or `info `.

Another tip is that the `apropos` or `man -k|--apropos` command can search all man pages for you. Also there are hidden man pages, like `man 7 signal` instead of just `man signal` (try it). `apropos` can find those for you.

Getting faster at reading is a key part of this, I spent some time exercising my eye muscles and it does help. (Eye Q) was the name of the software I used, I plan on revisiting that again.

I also spent a lot of time reading technical books, which _only_ helps if you practice the information you learn. Otherwise it just goes in and out. You want to take knowledge and turn it into skills, by practicing. Deliberate Practice to be more specific per the book Peak by Anders Erickson (must read for all learners).

At any rate, don't be afraid to ask and use StackOverflow, we don't all have many hours to find answers, we need to be effective, that includes reading a lot, but also knowing how to search, very effectively. Search Engines are a manual in a sense.

> I am a new college grad working as a Software Engineer...

I don't want to sound harsh but...How did you manage to earn a college degree without learning how to research specific topics?

That's pretty much all I did in college, I tried to "pivot" a while back and started at one of those private universities and was truly offended when they said I had to take a course on "researching topics" or some such nonsense and wouldn't let me out of it when I said "but, Dude, I have an art history degree..."