Hacker News Reader

Comment by jimpudar | Hacker News Reader

Also related - don't read random tutorials on "how to do X", go and find the official documentation for X and RTFM. In my experience this is the easiest and most direct way to learn any new technology.

View on HN

> go and find the official documentation for X and RTFM.

Yes and no. The official documentation can be obtuse and bad for new learners. (I'm looking at you, gradle[1]). Ideally, the official documentation includes tutorials, but also three other forms: 1) how-to guides showing the steps for accomplishing a common goal. Think of them as extended FAQ answers. 2) simple reference docs. Your typical api-centered doc, or man page cli flag list. Answers the question of "what was the function/class/flag to do that?" Assumes you already know how. 3) explanations, the discursive articles about how and why. A lot of people can get by with never reading these, but once in a while they can clear up some problem you're having. The tutorials, which should exist, would be short guides for learning by doing. They aren't how-to guides, because they don't assume you know anything yet. They are often the best entry points for picking up something entirely new.

[1] https://www.bruceeckel.com/2021/01/02/the-problem-with-gradl... and https://melix.github.io/blog/2021/01/the-problem-with-gradle...

I’ve had the opposite experience. I’ve attempted to read a number of specs, and by the way I’m completely unable to parse them, you’d assume I was illiterate. On the other hand, I’ve found good, technical articles detailing how the same things worked and have found them much more digestible.

For me personally, the answer is a combination of the two. Having the docs open side-by-side with a good technical write-up usually helps me understand a lot faster and better than either resource does on its own.

Sometimes the official docs are just right. Django is good, for example. I had to do small Ubuntu sysadmin task recently, the tutorials I found were incomprehensible. The official docs were crystal clear.

But we've all seen the reverse, as well, and a combination of SO, YouTube, Reddit, and random tutorials is the only way to figure it out. Especially when you encounter the "This describes version 3.1, and everything in 4.5 is completely different, good luck" official docs.

If you're competent enough to judge the technical article's credibility, this can be a good supplement to the official docs. I see junior developers running into this problem more often because they don't know how to tell the difference between a quality writeup and a garbage tutorial written by somebody trying to pad their blog.

There are definitely cases where the official docs (or RFCs) are practically incomprehensible to a newcomer, but I usually will try and come back to them quickly after getting a foothold using a blog post or YouTube video.

I find that even with the best technical writeups, there are often things applicable to MY use case that may not have been relevant to the author. The official docs (or sometimes the source) is the best place to find out about those.

Eh, I have the opposite experience. When I was a beginner in a any language, RTFM didn't work for me because:

A) Reading a manual requires some requisite knowledge due to esoteric references.

B) RTFM is a skill in and of itself.

C) Manuals rarely mention corner cases or "gotchas" which can cause confusion to a beginner.

D) Manuals never comment on best practices, which tutorials do.

The F'ing M is often an afterthought, and sometimes you need to dig into the source code to understand how the thing works, or at least to find the right handles to grasp.

Not necessarily the right approach for beginners, but I've wasted a lot of time trying to find the thing in the documentation, when I should have just lifted the hood in the first place.

This! There is very little selective pressure reducing the quantity or visibility of bad intros/tutorials. But for successful projects, the community puts a lot of pressure on the improvement and accuracy of core documentation. Truly complementary tutorials often ended up getting linked from or incorporated into primary project docs/pages -- so it is safer to explore from there than a Google search.

And it's much, much rarer but equally as important corollary: UTFM (Use TFM). UTFM means: when you're designing a system, adhere your design so f**ing tightly to standard usage. RTFM/UTFM with standard tooling gets you so, so far to building high-quality software.

Edit: I actually just made up (as far as I know) UTFM, but I really wish it were a thing.

I recently found the need to teach myself Java. While the Java Docs and official Java tutorial seem to be decent, especially once you know what you’re doing and want to dig deeper, the “Baeldung articles” have been really useful as starting points as a survey of options available. Since this seemed like a pretty random website, I’ve been cautious and cross referencing everything I read. But I have to admit, it was pretty damn useful.

So unofficial tutorials do have their place in introducing design patterns or listing trade offs between different approaches. But I do agree the source of truth should still be the official docs.

Reply on news.ycombinator.com