Learn new technology through writing a tutorial about it
nanxiao.me
nanxiao.me
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.
You mean "how not to do things in a stupid way", right?
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).
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.
I’d rather say, “no tutorial? Ok, to the docs like the old days,” than be misled by a shitty tutorial.
Idk about HN-ers, but I find myself in this situation at least few times a week since the beginning of my webdev.
There are many more poor quality tutorials written than high quality tutorials because high quality tutorials are much harder to write.
The writer has to know the domain, be up-to-date in the domain, have the communication skills and the time to write and edit.
Learning math makes you feel stupid.
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.
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
There's your problem. If you are writing a "here's how I did it" post, you should be clear that you don't have any idea what you're doing.
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.
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).
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
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
Well, Google should have done that from the start and there wouldn't be a problem...
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.
[0]: https://codeblog.jonskeet.uk/2010/08/29/writing-the-perfect-...
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.
First, some people probably will find what you write to be somewhat useful. Second, it's the absolute best way to learn something.
In your example, the problem was Google, not the myriad of people learning and writing what they learned.
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.
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 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.
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.
No. If he's an expert at gaming the SEO game, then maybe. Or if he gets super lucky.
> 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.
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)
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.
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.
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)
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.
> 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.
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".
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.
Bad blog posts can mean hours of wasted time and technical debt accruing in your solutions.
Sometimes I talk to or help someone and remember a post I wrote that could help, and share it.
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.
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.
Link to my tutorial:
https://github.com/thewhitetulip/web-dev-golang-anti-textboo...
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
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.
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.
To be fair, the hostile hiring environment rewards having a blog and a Github disproportionately
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.
on edit: changed object deconstruction to object destructuring, error came from hurried writing just as train came into station and I needed to run.
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?
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).
What caused you to 'break the chain'?
Was it getting a chore just to come up with technologies to explore?
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.
[0]: Web scraping with BeautfiulSoup and Requests in 20 lines of code. http://www.kashifaziz.me/web-scraping-python-beautifulsoup.h...
[1]: A proxy rotation script. http://www.kashifaziz.me/proxy-server-rotation-python.html/
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.
The notes: https://scripter.co/notes/nim/ (continuously work in progress)
This is the best experience I've had of learning so many other programming languages in the past.
- 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)
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.
Take a look at a Monad tutorial to see what I mean...
Most often someone who already knows a bit about some language will explore a framework which they have no knowledge in.
Results vary...
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.
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.
I'm thinking of taking the #100daysofcode challenge, but instead of coding doing 100 days of coding tutorials and walkthroughs.
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.