That's how we ended up with 1000s of garbage quality tutorials for android development. I was once looking how to save app specific data and all top 10 tutorials in google and DDG were saving data to userspace by creating new directory called something like 'myapp'. Years later Google had to create a series of tutorials with Udemy (as I recall) to actually tell people how to do things in a not stupid way.
Please don't write tutorials about things you do NOT know. Newcomers will visit your blog and think you're an expert and do it this way.
Just be honest with your readers by stating your level of expertise when you're putting material out there, whether it's a blog or a book. Besides, even if we got rid of the 1000s of garbage quality tutorials, there would still be 1000s of expert quality tutorials that are nevertheless worthless because technology has moved on and made them obsolete. Of all the many books and blogs published around technology each year, very few will be relevant the next year, let alone make it to timeless classic status.
But that still fills search engine results with garbage I have to filter through. It's hard enough searching for solutions to problems when there's five StackOverflow answers with full of bad data and incorrections scattered through the comments, answers, and comments on answers.
Interesting. I don't have any opinion on the incidence rate of low-quality technical tutorials, but I think this is the first time I've seen Google search results analogized as a fragile public good we all have a more-or-less moral responsibility to be good stewards of.
Exactly. No tutorial claims to teach you EVERYTHING about the subject. A tutorial is a light weight introduction to a topic.
You're using it wrong if you expect it to be prod grade. New comers have a big task of understanding the language & framework. Writing "prod" worthy things is the last thing on their minds
this is why (esp w/ js) I always use the google search w/in the past year feature. When looking for src code for ideas on ghub, I always sort by last updated or most starred but make sure the ones I check have been updated in past year... etc... Standards change so fast, and I feel coding is getting 'better' in terms of processes, that doing it like they did in 2015 is a step back sometimes, plus js itself has changed a lot, so has laravel, and other frameworks. Always good to get the latest data on something.
As a side note, I've found some 'gems' from tutorials that I knew were shitty novices or intermediate devs at best just writing to expand their career or do inbound marketing or something, but they made me think about a solution to something differently, or they touched on something I didn't know anything about, having never done it before like some api or auth system.
TLDR: I think with all tutorials it's buyer beware - especially coding tutorials, filter by date, don't expect perfect 10x dev tips unless you're on egghead, laracasts, railscasts, pluralsight (some other coding mooc that claims master level expertise), and if you write posts as a jr/intermediate dev, maybe try coming back to them when you 'level up' and make them better/more relevant.
Definitely agree with your tldr, there's some responsibility on the reader side as well. Even when authors don't declare their expertise, the context of the information, which might just be its age, can often be enough. You should know what you're getting when you read and take examples from the old PHP doc commenters, for instance.
I was setting up emacs + evil mode the other night to give it a real spin for the first time, one blog post from 2014 was pretty helpful but I suspected I'd have to throw out a bunch of things (if they worked at all) as I got further along and learned more about the ecosystem. Sure enough the way people add packages has changed, but this blog author helpfully updated the post in 2016 with the new information (and left the marked-as-old info there for context).
Yeah, part of becoming a better coder, is learning to scan through the 'chaff' to get to the good stuff. I'll usually open 5 different articles at once, scan em, see what applies to my situation the best, which one seems to 'know' their stuff better, etc...
One reason I hate video tutorials -- I don't want to sit through 30 minutes to figure out the 20 second tidbit I need to know, I don't even read 50% of blog posts I just scan it for what I want and go... lol
I've umm'd and ah'd over this as well, thinking it'd be a good idea to have a structure to learning by basing it around teaching others - and then I think about the number of tutorials I've gone through, only for the last paragraph be "obviously, that's not how you'd do it in production" with no next step and wanting to punch the screen.
If you're going to teach things, make it actually work for what the person reading needs. Personally, the chances of me reading a tutorial for interest vs wanting to accomplish a task are minimal.
Tutorials for learning, articles for interest. I'd say you could do the latter without expert knowledge, but the former needs to be pretty tight.
(All of this with the knowledge that imposter syndrome is so prevalent that we don't want to put off technically brilliant people writing tutorials when they think they might not be up to snuff).
Tutorials are for getting quick bootstrap on the platform. If you want to learn how do something in production, there's usually a manual or official user guide in place.
But why would you want to bootstrap your knowledge on something detached from your actual use case?
Lots of people on HN bemoan the lack of formalised education and crappy code stitched together, but that's what half arsed tutorials and impenetrable documentation breed.
To be honest, this sounds like an issue with search engines. Why are "garbage" tutorials getting high rankings in search engines? Why aren't good quality tutorials rising above them?
>Why are "garbage" tutorials getting high rankings in search engines?
Because John experiments with X for the first time and writes about it on his blog. Janette has the same problem while learning about X so she takes his code, makes a few changes and puts it on her blog. This scenario happens 8 more times and we have 10 low quality tutorials about how to do things, but none of the authors has experience and expertise in X, and they won't admit it. Bad practice is copied to many places. 1000 garbage kill 1 gold.
The same exact mechanism (and the parent already alluded to it in his comment: "Janette has the same problem while learning about X so she takes his code, makes a few changes and puts it on her blog").
Non experts look for tutorials,
They chance upon tutorials by non-experts
They don't know enough to tell they're junk
They use the code, link to, and suggest those tutorials to others
Those tutorials are getting higher ranks, attracting even more non-experts
Because search engines don't rank quality of source code and tutorial, they rank page layout, bolds, italics, font color and page speed. Literally any garbage can get to top3, you dont need to be good Ruby tutorial writer for it.
Because search engines are designed to show what’s popular, not what’s correct and thorough. Search engines still cannot weigh an article’s sense, only its “pagerank”. This is an issue with people, not with a search engine.
Because a garbage tutorial isn't necessarily incorrect. The solution in the tutorial might be slow, inefficient, un-optimized, hacky, etc., but if it works when people have been slamming their head on the desk for hours, people will use it. It's a matter of which tutorial captured the audience first.
Because people find them using search engines optimised for popularity (not quality) of content, as perceived by the readers, not a community of experts.
Keep it to yourself, then revisit it a year later and laugh at how little you knew. Maybe then update it and publish it since it will have both a beginners perspective and an experts perspective.
There is a high possibility that you'd be surprised how many dark corners you visited a year before. Depending on the subject you may deal with quite small surface area on the daily bases while preparing the tutorial you had to dig much deeper.
I do feel your pain with these crappy tutorials, and many of them are glorified blogspam or recycling/reheats of the same thing you could have already found out by reading the docs. There's no depth, no referencing of documentation, very little reasoning about why the thing you're explaining works.
That said...ideally if the author abides by (1) do proper research and (2) "Your tutorial can be reviewed by other brilliant engineers who can point out your mistakes" then there's no reason why you couldn't produce a reasonable quality tutorial in this way.
I think this article is written for developers/engineers who's overall skill level and expertise is a cut above inexperienced folks who're just starting out. i.e. you know how to research, you have a working familiarity with the tech stack you're working with (and broader awareness of other tech stacks), you know how to ask a "good question" on Stack Overflow (or have read and understood Jon Skeet's "Writing the perfect question" article[0]).
It's kinda like taking rubber ducking to the next level and sharing your learning experience.
Writing is one the best ways to learn something. It doesn't follow that that writing should be published.
The problem with blog tutorials is that it is democratization without meritocracy. There is no curation mechanism to bubble the good stuff to the top. Search engines rank by popularity, not quality. At least with forums and Q&A sites, there are natural feedback/reputation mechanisms to achieve some semblance of quality control. Blogs don't have that (they only have commenting, which depends on someone caring enough to comment).
This results in very low signal to noise, and a tragedy of the commons situation happens. In most systems, there is a cost to high-volume low-quality content because it discourages participants. (I don't know if you remember MySpace...)
You can't stop people from publishing low quality content, but if only there was a way to curate such content based on some standards (not gatekeeping... but curation). Quora tried and was successful in the early days because it started with a high quality contributor base, but that base has now been diluted and the platform no longer offers an enjoyable experience.
The alternative and positive aspects of this is that new people learning provide their own experiences in the current process of understanding at a basic level. And with that the problem areas or more difficult concepts or just interesting solutions to figuring problems out will have recently discovered routes and tricks on how they overcame those obstacles, versus when experts speak only like they are teaching other experts.
This especially is annoying when there are simpler parts of some of these currently dense technologies and it's just a bunch of jargon, of what is supposedly introductory content.
Newcomers should learn by reading the official documentation first and maybe some "official" books. In my opinion blog posts should be about very custom things or more specific use cases. Like integration with different technologies, hidden features or advanced stuff. If I want to learn React, I won't be looking for blog posts or googling "how to create a react app". I'll go to the official documentation, then grab some classic book endorsed by some community.
If you want to learn the whole thing then yes, but a blog post can be a nice 'easy' tutorial that lets you start using the technology with far less initial effort, and then you can learn the rest modularily according to your needs.
Another problem is that thousands of turorials get few to none updates. It’s not unusual to google for whatever.js quirk and find yourself in a tutorial that uses method that was deprecated 2-3 versions ago. Of course part of this problem is in whatever.js itself, that bumps versions like hell, but you end up with tons of crap that will be never relevant anymore, but still hit the top because its author still writes popular articles.
Idk about HN-ers, but I find myself in this situation at least few times a week since the beginning of my webdev.
Yes, please write your tutorial. The best way to learn something, by far, is to teach.
To those who say "but we don't want another crappy tutorial we only want to hear from experts" I heartily disagree.
First, it is your responsibility as a learner to decide if something makes sense or not. You can not and should never just believe something on the internet. Even experts get things wrong. Keep asking "why" while learning.
Second, experts are far detached from the beginner's mindset and often lack the ability to explain something in simple terms. Someone who is a few steps ahead of you will have a better chance to explain things in your language.
We need to spread more knowledge, not less. A beginner's experience with learning a new technology is valuable knowledge, even if some details may not be correct. As long as the reader keeps his critical thinking hat on, we all win.
It's great that there's loads of tutorials out there on most topics. it's not so good that so many of them are crap, or straight up wrong.
> it is your responsibility as a learner to decide if something makes sense or not
I disagree. It's on the teacher to explain clearly and accurately. If you can't meet that low bar don't pollute the net. The beginner is usually unable to decide which piece of conflicting advice or misinformation is correct.
For a great example of this see the php reference and the dozens of conflicting comments and recommendations on each language feature. A beginner has none of the nuance needed to decide which are helpful and which are misunderstandings. Or w3schools for an endless litany of poor and partial explanations.
> experts are far detached from the beginner's mindset and often lack the ability to explain something in simple terms
Again that's on the teacher and it need not be the case that an expert is detached (Though some can be). Explaining in simple lay terms is a different skill that is entirely unrelated to expertise of a subject.
You don't need to be expert to write a beginners tutorial, but you really should have the foundation firmly fixed (and validated by others or use) and reasonable ability to write clearly.
Until then writing a "my experience learning x" blog is a far better service to the internet. Save the tutorials a month or two more for when you have enough grasp to be helping rather than hindering.
I'm not saying it's fine to create low quality on purpose, obviously, any writer should aim to create the best content possible.
The problem I have is the reasoning that just because someone is a beginner there's no value in publishing his or her stuff. Any real effort has value. The more the better. It's new material that others can build upon. For example, it's a great opportunity for curators digging out the good stuff for others (I partly do this).
Besides, when does someone become "expert enough" to be sufficiently useful to publish? Who decides that?
The other problem with the argument "please don't publish, you are spoiling my search engine" is that it is not realistic at all. Everyone writes now. That's why we all need critical thinking and ask "why" and "does this make sense". A writer shouldn't pretend to be an "expert" or make false claims but this does not mean it is realistic to demand this (and I'm not even starting to talk about fake news etc)
"First, it is your responsibility as a learner to decide if something makes sense or not."
That applies only to the most trivial of subjects. Most complex things worth learning are so opaque to complete outsiders that it's impossible to discern good advice from bad. In the most complex domains it all appears gibberish, and the only thing that you can trust is that the teacher knows what they are doing, and that in the end it will all make sense.
Teaching things without any understanding of the subject is folly, and is actually dishonest. Just like portraying as a "healer" without any concept of the cure or the decease is dishonest and unproductive. Yes, you can help people without medical degree, for example in giving physiotherapy, but you really need to know your muscles, joints and therapies then.
The role of the teacher is holy and venerated, and for a reason.
Please don't make it cheap by saying "anyone can and should do it, and let students pay the prices".
Anyone can and should do it, but only after they have paid the price to master the subject in sufficient complexity to actually offer any advice worth sharing.
Informally helping colleagues is cool, but in that case you are sharing much more common context than in a semi-anonymous blog post.
I usually keep facepalming myself when reading turorials. The problem is not that I stop asking why, the problem is that before I can find a good one, I have to dig through piles of trash from popular guys who “just tried it and it seems cool”. They basically spoil my search engine.
Even if I had time/will for this, it’s a game against a horde of professional writers. I don’t believe it will work that way and that it will save my time at all – and there are tutorial places out there, all flooded with low-quality content in the end. Currently topmost “please no” comment is a best approach, in my opinion. If they simply stop writing tutorials while not being tutors experienced in topics, it will suffice.
First, it is your responsibility as a learner to decide if something makes sense or not
If one doesn't know anything about a topic and comes across two tutorials - one written in broken English (because the author is not a native English speaker) but the steps are accurate and other written in perfect English but the steps are wrong, it is highly likely they'd pick the latter.
That is just one example. Often, it isn't easy for beginners to tell good tutorials from bad, especially for highly technical topics.
In matters of all things that is technology, I am totally beginner. And when I am totally beginner, I have no way to decide which one is good tutorial. This had actually happened to me. I learned a lot of wrong stuffs and that is not the bad part. The bad part is that I realized my mistakes way too late and often in painful ways.
First lessons are the lessons which usually stick with you for a long time. It shapes your take and mindset about technology. For example, to learn C, I picked a book 'Let us C' and some blogs written.by novices. At that time I knew nothing about either C or this book. Much later I realized that book is utter garbage. This affected me badly. I had to relearn C and even now I can see I still think in C in the ways that crappy book taught me.
> A beginner's experience with learning a new technology is valuable knowledge, even if some details may not be correct.
This is so true. I think I'm a better teacher of javascript than design, simply because I'm worse at JS and find it easier to take early learner perspectives when I write tutorials (http://getfirefly.org)
Excellent points. I've come to appreciate that this explosion of tutorials and choice on the modern web is not a bad thing.
It seems rather like keeping up with the news - you can either read for (maybe pay for) one high-quality, authoritative guide. Or alternatively you can skim many and develop your own sense for quality and veracity by noting the similarities and contradictions between what they each say.
You put me on a roller coaster of agreement and disagreement. I don't want want to frame beginners publishing amateur level tutorials and "bad" or "evil" necessarily. I DO think the apparent "internet pollution" is worth considering in the context of "what helps us as a community".
> Yes, please write your tutorial. The best way to learn something, by far, is to teach.
I absolutely agree! This one of the reasons school and university is great: you have tons of peers at about your level of knowledge and who need only the level of rigor you can supply. School work is fantastic at avoiding the kinds of robust rigorous information production work needs.
> To those who say "but we don't want another crappy tutorial we only want to hear from experts" I heartily disagree. First, it is your responsibility as a learner to decide if something makes sense or not. You can not and should never just believe something on the internet.
I agree with whomever you're quoting. I don't want wade through hundreds of crappy tutorials. We don't need experts per say but intermediate skill and some actual experience goes a long way. I think the appropriate tone and style of writing can go along way towards mitigating the frustrations of "internet pollution". Putting the onus partially on the learner is reasonable, but if all of their resources are poor or wrong theres only so much you can do.
> Second, experts are far detached from the beginner's mindset and often lack the ability to explain something in simple terms. Someone who is a few steps ahead of you will have a better chance to explain things in your language.
This is too true. Experts aren't always the best resources, but beginners are virtually always terrible. I think the keys is here it sucks when you're learning something but it turns out the author isn't a few steps ahead but a few steps off the path in a sand trap.
> We need to spread more knowledge, not less. A beginner's experience with learning a new technology is valuable knowledge, even if some details may not be correct. As long as the reader keeps his critical thinking hat on, we all win.
Mixed feelings.
My proposal:
If you're just learning working with your peers (in a very localized), teaching others, and writing your experiences is invaluable. You've gotten all the value you're going to get from it. The broader community doesn't have the context of what level you're at so they're not likely to get a ton from what you're doing. Publishing this is probably not bringing anyone a ton of value unless it's pretty narrow like a messaging board for your class.
When you're at an intermediate level and you have some experience under your belt I'd say putting your ideas out there is the only way to get to the next level. Bringing beginners up the rungs with you is important. It's okay to be a little wrong if you're tackling bigger topics but this is also the level when you're a "reader [who] keeps [their] critical thinking hat on". You know where you're publishing something that fills a need.
In my opinion, we have far too many "Getting Started With [technology]: Part 1" tutorials and not nearly enough lessons on advanced topics. I get it, creating these lessons takes time and dedication that often isn't apparent until you're nearly done. I've started work on combating this phenomenon myself by creating lessons that do cover advanced topics but even those fall short of where I'd like them to be.
When it comes to "writing a tutorial" for the benefit of your own knowledge, it's been proven to work. This is very good advice when it comes to personal gain. However, for the sake of beginners and content creators that are active in the tutorial community, please consider throwing out these lessons when you're done. It might help someone out there at some point but you have to take into account your initial motive: personal advancement. Lessons that are taught out of passion for teaching and advancing the knowledge of those around you are often the best because they come from a selfless place. Lessons created for the creator's own advancement are often not as helpful. This is something I struggled with when creating my own tutorials. Was I creating it out of love for teaching others, or was there some hidden motive that even I might not be aware of?
This is simply my own opinion, take my comment with a grain of salt. I'd be interested to hear what others think about the prevalence of "beginner" tutorials juxtaposed with an apparent lack of those that would be considered "advanced".
For me, it's the rare errors/workarounds that need more love. It's not rocket science to learn Python, yet we somehow have literally 100's of guides on how to start learning Python. Once you dive into a particular niche method, though, there may be a couple of SO posts unanswered or with unsatisfactory/ungeneralizable results. If you don't have an experienced mentor and you're on your own, I find that situation pretty hard to deal with. It may be some basics that you're lacking as an intermediate, non-advanced practitioner, because you relied on this patchwork of beginners' tutorials limited to the main/easiest tasks in the language. When I was learning R, the tutorials I looked at didn't mention selecting columns with $, which was a very poor oversight and led to some "dumb questions" to my mentor.
Write all the tutorials you want -- teaching is a good way to verify and refine your own understanding -- but please don't feel compelled to publish them! As other posters have said, this is how we end with thousands of low quality tutorials and bad StackOverflow answers.
Publish if you have something new to say, or a new way to say something. The (very very few) articles I've published fall mostly into the second category, and have been extremely well received.
Not wanting to defend SO, but reading a question, thinking about the solution, scanning the documentation, does help me to learn something new. If I stumble across an answer, even better.
I've tried that, but I found that writing a tutorial consumes too much time when writing for a wide audience. So, I started writing tutorials for myself. It's brief, covering the most important steps which do not explain much, but it gets the job done. That way I needn't going through the research process all over again for the same thing I did some years ago. Later I might decide to share that knowledge, but again, editing it for a larger audience costs time.
If I need to learn something technical (new language or platform etc.) I build out a Word document with proper headings and dump all the keep info into that. They are not tutorials per se, but they make sense to me and once written I end up knowing far more about the subject in less time, than if I'd just read about it online. The sheer act of re-writing down the information helps me commit it to memory.
yes this is what I do. I have a blog, that nobody reads. I write about tech and non-tech things, without stress of fears, because I only write for myself, like my personal, public notepad.
Sometimes I talk to or help someone and remember a post I wrote that could help, and share it.
I learnt Go programming language & writing webapps in it after reading loads of books and articles which suffered from the curse of knowledge.
I'd start with the first few chapters and then would be totally clueless.
I figured out that the curse of knowledge is huge. Once you learn how to write webapps they become trivial and that's the reason why few books written by "experts" targetting newbies are utterly of no use.
But of course that doesn't absolve the tutorial creator from her responsibility of writing a decent tutorial and with the advent of Github it has become a collaborative effort!
It is a sad thing that masters write books for beginners. No, a beginner shouldn't be taught how to use the stdlib, they don't understand half of the things (prose) mentioned in the book.
Lead by examples, show that it is not magic and that it is actually very easy to write a webapp in Go but it ia difficult to write a really good one.
I later did the same with Vue.js and Python but didn't get time to finish/update them.
I also run or used to run a youtube channel which also has got good positive feedback from new comers because they get to the point with practical examples
The article is extremely short, but the three points it makes resonate with my experience--but not the title, since I usually end up writing tutorials about subjects I am already quite familiar with but written with a specific audience in mind (my own tech teams in the past, specific customers these days).
Regardless, the points are valid:
1) You will find that you need to clarify what for you are intuitive leaps or gaps in detail so that someone else understands them
2) Peer review and feedback often improves the quality (and reach) of your document
3) Language matters. Regardless of language skill improvements, reach is paramount, and I recall when it was somewhat unpopular to write technical documentation in English in my neck of the woods.
Today that's mostly moot, but something to consider.
As an anecdote, when my team was moving to c++11 I decided to give a presentation on the important features, and when they should be used\avoided. I thought it would take a couple of hours to make a presentation, however it ended up taking me a fair bit longer because once I decided I wanted to tell other people about features, I felt I needed to know them inside out to be able to explain the inevitable questions.
What ended up happening was I gave my presentation and (I hope) the team learned a bunch, but I probably got the most out of it I think. I understand a lot of those concepts at a deeper level than I did before, and it's helped me a lot in my career.
If you try and find tutorials or examples on something in C# I would say that 90% of it's pure garbage
Yet the bloggers of these pieces write in such a way that someone with little experience would look at it and think the blogger knows what he is doing. Often the code is so far removed from what would be deemed production ready that the trivial, and poorly implemented, example is absolutely worthless at best and at worst quite misleading.
I don't understand the ego of wanting to have a blog and talk about something you clearly aren't an expert in.
This is good on paper, bad in practice. One of the best ways to retain and understand information is to explain it to yourself. As in talking, having a conversation with yourself(I do this very frequently). It makes sense that to show you understand something at least on a beginner level, to create a blog/video/tutorial to teach others about what you just learned. As many others have stated though, this leads to a mass of useless tutorials being created and pushing down the actual good information about that topic in search engines.
There are ways around it, disclaimers are a good start. I'd put in a very visible style, a note that says something like "I by no means am an expert in the field, I only just learned about this topic and am creating this tutorial to try an re-enforce my own knowledge. This information is not assured to be valid in any way and it should not be cited or used as such."
Even after saying that, I'd still encourage this behavior on personal blogs. No one should be taking technical information from a personal blog without additional research on a topic anyways. Many people have blogs for themselves, not others. The action of some people stumbling upon a personal blog is just a coincidence/bonus. Back when I was first getting into infosec, I'd write personal tutorials on exploit techniques(cross-site scripting, SQLi, LFI, RFI, etc). I never posted them, because I didn't care for anyone to read them. They were just for me so that I could re-enforce what I already learned.
Is this what people are doing on all those little technology blogs where they talk about some particular technology and it's always the same code with just slight alterations used as examples?
Cause I noticed this yesterday when I wanted to find a particular example of Object destructuring.
on edit: changed object deconstruction to object destructuring, error came from hurried writing just as train came into station and I needed to run.
+1 - I find that this is a great way to learn new things.
I personally felt like I was falling behind on modern java (generally I only do golang + typescript at work) so I started building a website with some simple examples/tutorials with small commentary partly to give me an excuse to write something using the new toys, and partly as a quick reference for myself. I was inspired by the gobyexample.com site.
If anyone has any comments on what I've done so far, I'd be keen to hear your thoughts:
One thing that bothers me about this "learn it yourself then tell others" appriach is I am concerned that I might be missing best-practice and the general zeitgeist on what is "the way it is done". E.g. years ago gradle was the "way it was done" in Java for config management, but what is it now? I've got no idea.
How do other people handle this? Apart from wildly searching around, how do you keep abreast of current trends and best-practice for development if you're not living and breathing it in the day job/open source?
Yesterday I was learning React, and I wondered whether there was a React abstraction for http requests. So I found a tutorial for making a request in React, and it was spread over 3 different articles.
The first article was about how to install React. The second article was about how to set up a basic click event in React. The third article showed you how to use a 3rd party JS library for making an http request.
But once you're done, consider whether or not you should publish the tutorial. At a minimum, have it reviewed by people that are in the known, and will give you honest feedback (insist on that).
After procrastinating for quite some time, I finally picked up Python and fortunately got a web scraping assignment. Once I did the job, I thought to share the process online so that others may benefit from it. [0] and [1]
As I deep diver into the wonderful world of Python, I plan to document my Pythonic journey, noting that things of interest, the obstacles I come across and how I try to push my way through them.
I agree with the OP. Learning anything new is best done by noting down even small taken-for-granted things, things that you wouldn't care much about once you have mastered that thing.
I have been using this technique to learn the Nim programming language.
I write notes (semi-tutorial) about this language as I learn more about it. I explicitly mark things as "need to understand" or "todo" so that anyone browsing these notes knows that it's not written by a Nim expert but a Nim learner. And also the notes as strictly labelled "Notes" to make that explicit.
I like to break down need of understanding into a few categories:
- no need to memorize or understand (some domain specific and infrequently-used portion of the API)
- memorize and understand later (it's better to just continue and get a holistic picture than to get off into the weeds analyzing how some framework magic works)
- you should comprehend this fully before continuing (general and recurring patterns for structuring your code)
I think that trying to explain something, is the best way to learn things.
You can go through 10 tutorials and think you "got" something, until you need to articulate it and you realize maybe you missed some step. Of course I'm generalizing, but I also find this process helps "stick" things into my mind. I might completely forget something 1 week from now if I don't put it into writing.
I also find a huge waste keeping things on my computer, so I publish them. I started doing this on my blog https://flaviocopes.com with the things I knew already, and of which I had already lots of notes spread around, and then when I got "tired" of this I turned this into learning new things as well. I mix and match these approaches.
Sometimes I go into "series" of posts to dive into a tech for many days in a row.
I might search something on Google and spend 1 hour looking for the correct answer on SO or other blogs, and when I finally get the "canonical" one buried somewhere, or some different but valid solutions, I write a blog post to make it my canonical in the future (I find I very often reference my posts and update them as I go).
Writing down things as a learning process is worth it even if you just target yourself. I don't write to teach anyone. I write to learn, then if the result is good I think it's a disservice not to share the work with others.
Then I agree that crappy tutorials are not worth sharing most of the times. If you target beginners it's cool to write basic stuff, but it should be a nicely crafted content rather than rushing things and copy/pasting examples taken from somewhere else.
As a few other comments, and the well known adage, have noted the best way to learn something is to teach it.
But I do take issue with "write a tutorial about it", quite strongly.
Why is teaching so helpful to learning?
It forces you to reuse those recently forged bits of memory by accessing it, along the way it shows up any gaps or misunderstandings. Like rubber duck debugging the mere act of talking through an explanation shows up the gap, and you're missing the next sentence. Now you know what you need to read up on, or clarify.
Here's the crucial bit that writing a tutorial will give you NONE of: In teaching you will explain vaguely, you'll encounter loads of people who thoroughly misunderstand your simple and obvious explanation of, let's say, C pointers. Your explanation might even have been great but surprisingly they got distracted by their phone. Then ask all sorts of inconveniently difficult questions about why their pointer increment is doing strange things, or why the compiler is not happy. You'll sometimes even become completely lost trying to debug someone else's trivial example code.
I think the whole point of the advice to teach something to learn it is this second part. It's the difficult and inconvenient questions that do wonders for your knowledge. Even someone asking "but why?" can have you realising something you just accepted isn't actually that obvious. It takes you far off the few well worn paths in your memory of the subject. Writing a tutorial achieves none of this as you'll mostly write tutorials on the few things you think you know. But don't.
Thank you for making the internet worse.
Teach, then write a tutorial.
You don't need to be years ahead, or subject expert, just weeks or months. Pair programming over skype is just fine. One of the most ridiculous things my second employer did was insist that anyone attending a course taught the others in the office what the course covered the week after. Remarkably useful policy looking back.
Every time I read extensive tutorials, blog posts, what have you about something. I think to myself, damn, these guys have a lot of extra time on their hands. Generally I learn new things, by building something, and then building something that builds up upon that. I can't see stopping to write about it too! I dig it though, I do, without you I wouldn't have learned a lot of things. But it always amazes me the dedication to put all of that together, while working on other things.
It’s not that hard if you document things as you go, then at the end of it you have a tutorial and when you revisit 6 months (or years!) later you know exactly how and why you did something. On top of that most of the ones you’re reading online are written for inbound marketing, so it ultimately serves as a revenue source for many.
Of course, writing a tutorial about something gives you a way more thorough learning experience, but it is way more time consuming.
For me personally it works best if i use a technology productively. You will face challenges very fast and solving these will give you a huge boost of enlightenment.
Writing a tutorial is similar, but it adds the complexity of explaining it to the reader.
As a freelancer, I'm currently lazy and low on clients, but someday I plan on beefing up my tutorial landscape for the sake of inbound marketing. I also think job-wise 'quality' articles can show managers you know what's what and can also show you 'give back' to the community even if you don't contribute to opensource or anything like that.
I'm thinking of taking the #100daysofcode challenge, but instead of coding doing 100 days of coding tutorials and walkthroughs.
I feel the effort I put onto writing tutorials might be well invested in furthering my knowledge on that topic instead. There are plenty of books & YouTube videos, even the official documentation to go through if one desires to learn the fundamentals and beyond.
If there's anything we can learn from the activity levels around this post it's that you're better off writing a blog post about writing a blog post about development than you are writing a blog post about development.
Assuming you have some grasp of reality it's a pretty good exercise for Dunning–Kruger self-diagnoses. If you can write on a nontrivial subject without encountering it you've basically mastered it.
this is saying is the old adage “if you want to master something, teach it”
Personally, when I wanted to learn Swift, I found it useful to create a Github repo of example programs demonstrating a concept. I can easily update them for new versions of Swift and iOS.
Please don't write tutorials about things you do NOT know. Newcomers will visit your blog and think you're an expert and do it this way.