1. 20

Beginners are asking questions like “What’s the best tutorial for making X?” all the time. They genuinely mean it… In the post, I’m analyzing the hidden roots behind this question.

Emphasis on the “making X application”. Tutorials for specific tools, libraries and concepts are awesome. But asking for a tutorial on a super-specific application is a sign of not being able to split the task at hand into manageable chunks and apply existing knowledge to them.


  2. 16

    I absolutely need tutorials for every-freaking-thing, especially if I intend to not retain any of the knowledge and/or wisdom I accidentally stumble upon while following the tutorial, which happens most often in domains where I have no intention of cultivating expertise.

    Granted, those mostly happen to be tasks that require my hands to manoeuver something else than a keyboard, like “how do I sand a wooden floor”, or “how do I install a new wall socket without zapping myself dead”, or “how do I make bread”.

    If I want to retain expertise, I’m going to seek out introductory material to the matter at hand. And I’m going to pay attention.

    1. 5

      The article specifically covers the “making X application” kind of questions (and it says so in the opening), so a more appropriate analogy would be “how do I build a two-storey apartment with blue walls and disco ball lighting”.

      Questions that you listed are way more specific and relevant. But when people ask “how do I build a X app”, what they are really after is how to get there, but they don’t realize they need the exact tutorial for that (nor there is one).

      A tutorial on building an apartment, an article about caveats of two-storey ones, a video on painting the walls blue (or any color), and tips for sticking the disco ball to the ceiling would be separate, reusable pieces of content that could be used to answer “how do I build a two-storey apartment with blue walls and disco ball lighting”. Splitting a big problem into smaller chunks, and looking THESE up is where it’s at.

      1. 5

        Until you can analyze and decompose a problem, you’ll remain a beginner because you’re unable to help yourself or ask meaningful questions that are respectful of other people’s time. This will also limit the size of what you can build. That is fine, you need to put the time in to advance and learn the physics of building software.

        Additionally, I suspect the “making X app” tutorial requests have a “do the hard part for me and let me brand it as my own,” quality to them. I’m sure there are some legitimate requests there, too, but the hype of tech has brought in people who are work vampires and thirsty to Get Theirs: “All I need is a YouTube video on how to make my own social network, then I’ll compete with Facebook!”

        1. 2

          work vampires

          Saw the point you were making, scanned for the word vampire, wasn’t disappointed.

          I’m trying to do something to encourage and enable programmers to be more independent with the Almanac, but it’s really only for intermediate-or-advanced Haskellers.

          1. 2

            I love Haskell and your writing. When is the Almanac going to be available?

            1. 1

              Hopefully this year but no promises. It’s as much me hammering out the process we used to write Haskellbook as it is me getting the book itself done.

        2. 2

          My bad for choosing poor questions, really, I fully agree with all that you said. Thanks. :P

      2. 8

        tl;dr To the extent that tutorials are glorified examples, I find them extremely useful, even when I also RTFM.

        I love reading tutorials when I evaluate some library, language, or framework. I want to see what the workflow looks like, what the resulting code looks like. I don’t want to spend days / weeks / months / years becoming knowledgeable, I might not even end up using the thing I’m exploring!

        Even within this special class of tutorial use-cases there is variety. I love playing with new / weird programming languages, mostly for fun. I like to see what kinds of abstractions they make possible or elegant and where their tradeoffs are. Reading the grammar doesn’t give me that. I want to see some code, written by someone who knows more than I do about how to use the language. Tutorials are great for this purpose.

        On the other hand, when I evaluate libraries to use in production code at work I obviously take a slightly different approach. I want to know about things like code quality, the organization or company behind the “thing”, etc. I’m also much more likely to read through the documentation (after all, if I end up using the “thing” I’ll be spending a lot of time with the docs). But tutorials are still useful as a way to get familiar with something and the problems it attempts to solve. They also tend to highlight best practices within a community and the good ones touch on common pitfalls that might not be obvious to a beginner.

        So, to the extent that tutorials are glorified examples, I find them extremely useful, even when I also RTFM.

        1. 6

          Disagree. A few (somewhat interrelated) points.

          1. Our industry is very superficial and impressions held of us by people who are significantly less intelligent than ourselves still matter. I’ve seen people typecast as “slow” because they drew a bad first project or because they landed in an unintelligible pile of “boss code” that couldn’t be criticized because of the political success of its author. If you’re going to expect me to learn a new tech stack, the least you can do is give me pointers to what I need to know in order not to embarrass myself. If you can’t do this, then you can’t fault me for (a) asking stupid questions or (b) taking a lot of time to figure out how it works. I wasn’t born knowing how Makefiles work or how to configure a Flask app.

          2. Quality of introductory materials says a lot about the strength of a community (both in numbers and ardor). If the quality of introductory resources is not there, then it’s probable that there will be other, much more serious, issues (like security problems, build chain woes, and show-stopping bugs in core libraries that only occur under load) down the road that I wouldn’t possibly be able to spot until (unless) I developed an expertise in the platform– something that would require an investment of time that I may not be able to afford.

          3. As I get older, I recognize that I’m never going to learn everything and that a lot of being productive is choosing what paths not to follow. It’s useful to know five or ten languages. Five or ten web frameworks? Maybe not. I don’t care about ORMs. Those shouldn’t exist in the first place. For web frameworks, it might be enough to learn one or two and a smattering of notes about the strengths of the others. A tutorial helps me quickly get to the point of knowing whether or not I want to proceed. The lack of one is a signal that I should probably wait until the product or platform is more mature. It’s not that tutorials alone can bring deep knowledge, but a good tutorial gives me an inclination of whether I want to acquire deep knowledge of a topic.

          4. I didn’t learn C from a tutorial. I read books: K&R, 21st Century C, and a few others. If I want to understand a new machine learning technique, I’ll have to read a paper. I’m willing to do that. Some web framework that I’m expected to learn because some 27-year-old VP/Eng thinks it’s a good idea… is not at the same level of importance. I’m not going to dig for resources that probably aren’t there, and I’m not going to trudge through Stack Overflow answers on the assumption that I can separate wheat from chaff when it’s a platform I know nothing about. If there’s a book or a tutorial and I’m given time to read it (because I am done with those militantly anti-intellectual environments where “reading books on company time” is not OK) then I will give it a shot.

          5. Although I can learn hard topics without tutorials, not everyone can do so in a timeframe that our short-sighted corporate overlords will accept. Let’s say that I’m fully bought in. Even so, if there’s no tutorial, then there is no way in hell that I can (a) convince executive boneheads that the platform is mature enough and (b) convince a team to use it. I’d probably end up having to write the tutorial, and almost no company would budget the time for that.

          6. I’ve designed games, and one of the principles when writing rules documents is to write for “the stupidest person”. Obviously, that’s an exaggeration, but it’s very easy to lose sight of what is obvious to the designer but will seem like arbitrary complexity in the first exposure. Even if you write your rules document perfectly, you will have divergences in play. That’s harmless (even beneficial) for a tabletop game but it can create problems in software if users have different assumptions about the product than the creator.

          1. 1

            quite the laundry list, but picking out the orm commentary for a sec.

            orm != sql dsl. if you don’t have to write CRUD methods for every object you represent in the database that is a productivity win at a (small) performance hit depending on the language. .net is great in this regard because you can dynamically emit populate methods as if you wrote them by hand (versus having metadata hashes), leading to almost no overall performance hit.

          2. 5

            I’ll admit I mostly skimmed the article but I agree with most of it. This bothers me a lot with new developers who instantly Google for tutorials, courses, videos, etc. instead of at least trying to read the documentation, code, or test things out. It’s more annoying when coworkers whom you thought were more experienced than you don’t do work because they “are going through a tutorial first”. Sigh. I guess I get frustrated by devs who think they can get by from reading step by step tutorials for everything before thinking about the problem.

            1. 5

              A corollary for this is “you don’t need a library or gem for every freaking thing” (or, at least, you don’t need the library you think you need). A lot of less experienced developers I know, if they want to do something sufficiently complicated in, say JavaScript, will google for about 5 seconds and then choose the first jQuery plugin that comes remotely close to what they want to do, effectively copying and pasting some code into their app and then proceeding to hack the plugin to do what they want. I know this is a way to get going quickly, and if that’s important to you and you don’t have another option, then that’s what you have to do. But if you have the time, it’s better to take a step back, think about what you actually need, read about different approaches, and try to find a smaller piece that you can use more easily. Of course, it takes experience to know how make this kind of decision, but you also have to spend the time understanding the code you’re about to use and what problems it solves rather than throwing it into your app and seeing what happens.

              1. 2

                Another common problem with less experienced developers and libraries is adding the libraries without experiencing the problems they solve.

                I still see it often in the React community that people who are just getting started with React are trying to smash all sorts of things into the mix; state management (Redux, MobX, etc etc) is a super common one. Newcomers see mature projects using these and kind of assume they have to use these as well, without realizing what problem these solve. The end result is: people don’t know when one thing ends and the other begins, which only does them a huge disservice further down the line.

                So there are two different classes of YAGNI here: reaching for a quick solution and trying to Stay Cool™. From where I stand, the latter seems even more prevalent in the React community.

              2. 3

                I think you slightly missed the target. I would propose you don’t need a tutorial for any-freaking-thing, if you are Doing It Right (which nearly no one is, ever, especially not me); and that your ‘tutorial’ is a class of behaviour which includes e.g. cutting and pasting from Stack Overflow.

                Either you know how to use a tool or you don’t. If you don’t, you can read the fucking manual and gain that information, or take a shortcut that may allow you to get something done with less than complete information about how or why it works.

                I think the actual situation is more complex than your analysis:

                • Tools are incredibly complicated, and often have nuances and details that are hard to discover without R'ing a lot of TFM
                • Because there are common use cases which can be labelled succinctly in English, and magical incantations (a combination of input to the Tool which does not need to be fully understood to work) which work reliably for these use cases, it has become a behavioural norm to search for the use case and just apply the incantation.
                • Reading manuals, understanding the architecture of your tool properly is hard and long and boring and why would you do that when you want to get paid with minimum applied effort?

                The result of this is that it is possible to use the tools without understanding how they work because the incantations are readily accessible, and that sucks because it allows people with very low levels of skill or knowledge to initially use the tools in a superficially similar way to people who understand them and/or RTFM.

                Rendering a list? Well, it’s more about rendering arrays, and that is a solved problem. You can google “react render array” easily!

                This isn’t solving the problem at all, you’ve just slightly shifted the point on which your lazy programmer is looking for an incantation. The proper direction to give them, if you care about them being a good programmer is that they should understand the tool they are using well, and in this case the only correct direction to give them is: if you don’t know how to do something with react, RTF react M.

                1. 4

                  I’m focusing specifically on the “making X application” class of the question, which is always an indication of not being able to split the problem into smaller parts and research on that… like when you need a specific app and want to be shown how to make it.

                  Tutorials for specific tools and libraries and ideas are still viable — but it doesn’t matter so much which specific app the tutorial happens to build, it’s circumstantial.

                  1. 2

                    It took me several years (and many conversations) to realize that there are many different ways people learn things. Back in 96 (or maybe early 97; it was just a couple of years out of college) I was tasked with writing a meta search engine (a search engine that sent queries to other search engines) in a language I was not familiar with (Java) on a platform I’ve never programmed before (Windows 95). I didn’t cry over the lack of tutorials, I just dove in, but that’s how I work (growing up, I only had one other friend that had a computer and it wasn’t the same as mine—oh, and no Internet). It was odd to see just a few years later seeing requests for tutorials on writing meta search engines (it was thing back then).

                  2. 2

                    I disagree…

                    There is a ton of foundational material required to be able to read a manual effectively, being walked end to end through an application is a good way for beginners to pick up some of that material (stuff that isn’t in the manual, like the difference between a GET and a POST request).

                    The react documentation is a tutorial… Most documentation is only the “Reference” portion, and sometimes even that’s incomplete (at which point RTFM becomes RTFC).

                    Beginners really do need a tutorial for every freaking thing.

                    1. 4

                      For starters, the difference between GET and POST most definitely is covered in the manual: https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9

                      Second, nobody is saying tutorials aren’t useful for giving a high level view on a library, API, or language. The problem is when people use tutorials as a crutch and are unable to build their own application without following a tutorial. If nothing else, tutorials almost always skip a lot of details (like security, error checking, etc.) that are critically important in real applications, and the people who “need” to use them are the least likely to understand what’s missing.

                      1. 3

                        But is it in the React manual?

                        These are important details involving security and error checking that are critically important in real applications, the people who “need” to use them are the least likely to understand what’s missing.

                        There’s no beginner’s substitute for not being a beginner. Beginners really do need a tutorial for every freaking thing.

                        1. 2

                          But is it in the React manual?

                          Why would it be? Does the React manual explain how to use the terminal or turn on the computer?

                          There’s obviously no substitute for being a beginner, but there are lots of ways to learn new information and gain experience, and tutorials are only one way to do that, and aren’t very effective except for getting the most basic high level overview. At some point there’s no getting around the fact that a person needs a deeper understanding of what’s going on and how things work if they’re ever going to move past the “beginner” level.

                          I think we can all agree that at the very least a “beginner” shouldn’t be working on public facing production projects without a more experienced person to review what they’re working on and point out issues.

                        2. 1

                          Agreed. There are constant complaints similar to “can we have a real world tutorial that covers X or Y??” for many libraries.

                      2. 1

                        I think the roots are they don’t have full domain understanding of the problem at hand. Some problems it’s hard to predict how difficult it is to attain that knowledge, and triply so for a beginner. Does a raytracer have a lot of non-programming related information to build it? Does accounting software? What about home construction software? A tutorial can in many ways be a exposition of this non-programming knowledge, paired with some code that describes that formally.

                        1. 1

                          The only worse variant of this is when beginners specifically look for video tutorials for something that is super specific. Video tutorials jave their place, but I find having text to be preferable for scanning and such.