
Learn new technology through writing a tutorial about it - nanxiao
https://nanxiao.me/en/learn-new-technology-through-writing-a-tutorial-about-it/
======
akerro
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.

~~~
Jach
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.

~~~
pavel_lishin
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.

~~~
jczhang
Not the writer or publisher's problem imo.

~~~
pavel_lishin
It's also not my problem when I throw my garbage into the river.

~~~
gglitch
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.

~~~
firemancoder
It's absolutely excellent way to frame the problem.

------
amorphous
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.

~~~
oldcynic
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.

~~~
amorphous
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)

------
k1ns
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".

~~~
WhompingWindows
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.

------
ggambetta
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.

~~~
wenc
StackOverflow at least has a way for curating for quality through
upvotes/downvotes.

Bad blog posts can mean hours of wasted time and technical debt accruing in
your solutions.

------
dschuetz
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.

~~~
Jaruzel
Same here.

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.

------
thewhitetulip
This is a touchy topic.

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...](https://github.com/thewhitetulip/web-dev-golang-anti-textbook)

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

------
rcarmo
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.

------
MetallicCloud
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.

------
LandR
I do back-end C#, mostly.

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.

~~~
gaius
_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

------
Rotdhizon
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.

------
bryanrasmussen
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.

------
mosselman
I'd rather read tutorials from experts to be honest.

------
mattlondon
+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:

[https://byexample.xyz/](https://byexample.xyz/)

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?

------
tenaciousDaniel
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.

...

------
norswap
From experience, this works.

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).

------
shekhargulati
I did something similar in 2016 where I wrote tutorial on new technologies
almost every week [https://github.com/shekhargulati/52-technologies-
in-2016](https://github.com/shekhargulati/52-technologies-in-2016). You learn
a lot but as you don't end up using them you forget them .

~~~
sireat
Cool idea but I noticed you stopped after week 43.

What caused you to 'break the chain'?

Was it getting a chore just to come up with technologies to explore?

------
wordpressdev
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.

[0]: Web scraping with BeautfiulSoup and Requests in 20 lines of code.
[http://www.kashifaziz.me/web-scraping-python-
beautifulsoup.h...](http://www.kashifaziz.me/web-scraping-python-
beautifulsoup.html/)

[1]: A proxy rotation script. [http://www.kashifaziz.me/proxy-server-rotation-
python.html/](http://www.kashifaziz.me/proxy-server-rotation-python.html/)

------
kaushalmodi
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.

The notes: [https://scripter.co/notes/nim/](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.

~~~
rptv
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)

------
flaviocopes
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](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.

------
moomin
This is not a bad idea, but it’s not guaranteed that said tutorial will be
worth reading.

Take a look at a Monad tutorial to see what I mean...

------
dalacv
Or create a Udemy Course about it and make money while learning

~~~
sireat
This seems par for most courses.

Most often someone who already knows a bit about some language will explore a
framework which they have no knowledge in.

Results vary...

------
oldcynic
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.

------
overcast
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.

~~~
albertgoeswoof
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.

------
DrinkWater
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.

~~~
gremlinsinc
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.

------
sus_007
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.

------
vorotato
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.

~~~
hkon
I think that goes for most things, maybe it's easier, hence all the blogs
about how to start blogging etc.

------
tjpnz
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.

------
melling
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.

[https://github.com/melling/ios_topics/blob/master/README.md](https://github.com/melling/ios_topics/blob/master/README.md)

------
rutgar
Great idea, similar to the feynman technique.

------
Tomte
It worked extremely well for Mark Pilgrim.

