But now Joe goes and writes a monad tutorial called “Monads are Burritos,” under the well-intentioned but mistaken assumption that if other people read his magical insight, learning about monads will be a snap for them.
Publishing your tutorial gives it an audience, which means someone may (hopefully!) come along and correct you on your errors. This is invaluable.
I also disagree with this negativity. Make it clear at the top of your tutorial that you’re a beginner and you may not have it all right. But with that caveat, publish away.
Publishing your tutorial gives it an audience, which means someone may (hopefully!) come along and correct you on your errors. This is invaluable.
Absolutely invaluable, but at the very same time, the exposure spreads the misinformation to more readers, potentially doing more harm than good. I don’t think a disclaimer is enough. I think the word “tutorial” implies some authority, unfortunately.
I think a better way is to humbly share a report of your findings so far, with questions and an (as appropriate) admission that you don’t understand everything. Julia Evans is masterful at this style.
As a reader new to the topic, you get the benefit of an explanation of what she currently understands (which is often from a beginner’s mind), and usually some questions to seek answers to on your own. As an expert of the topic, you are invited to share more, or clarify, or correct (and this happens a lot on twitter, and/or HN, etc). But you’re doing so from a place of empathy (you want to be helpful) instead of from a place of disgust (ugh! why is this tutorial so bad!).
I disagree with the negative posts. Writing about something you’ve just learned is absolutely a wonderful way to cement the knowledge, record it as you understand it for posterity if only for yourself, and help you pull others up right behind you. It’s not your responsibility to keep your ideas to yourself until some magic day where you reach enlightenment and only then can convey blessed knowledge on the huddled masses, a lot of this stuff (the specific tech, for the most part) moves too damn fast for that anyway. Maybe we need better mechanisms for surfacing the best information, sure, but discouraging people (yes, even noobs) from sharing what they’ve learned only ensures we’ll have fewer people practiced in how to do it effectively in the future.
That said, I do 1000% agree that people writing in public should be as up front as possible about where they are coming from and where they are at. I definitely get annoyed with low quality information that also carries an authoritative tone.
There’s a world between documenting how you learned a thing, and writing a tutorial for that same thing. If you’re learning a thing, probably don’t write a tutorial. I agree with you, writing about a freshly learned lesson helps in making the learning more permanent, though.
In the case of projects, I’d rather see people committing documentation changes back to the project, at least here the creator of the project can review it.
It’s a free internet and nobody can stop someone from doing this, but, IMO, the problem with technology is not that there is too little poorly written tutorial out there. Maybe it’s worth finding other ways of being constructive.
Writing it down can help the mind remember or think on things. If errors are likely, then maybe they just don’t publish it. They get the benefits of writing it down without the potential downsides.
This is not a good idea. I have looked for documentation on many things that I needed to learn, as you do, only to find that the tutorials/introductory docs didn’t match any of the stated goals or aims of the API. Nothing quite as annoying as realizing the document you’re reading fundamentally misunderstands the thing it’s trying to document.
As mentioned by a few people, there are some flaws in this in what it means for you and your readers following it. Something I’ve considered a worthwhile approach, however, is similar to this.
We have a paired group at university where each week we pair off and learn about a particular subject. Later, we come back together and teach each other what we’ve learned. It’s useful to go head to head on the misconceptions you’ve each picked up, and you can correct and work with each other to both develop a better understanding.
As for me, writing tutorial is not an easy part of learning, especially if you are not pro in area what are you writing about. I would recommend writing a pet project first, share and learn for a community and after that you can write a tutorial :)
please don’t. When learning you make a lot of mistakes. And writing a tutorial with this mistakes doesn’t help other learners when they read this.
And even if you don’t make mistakes, most people will misunderstand their own process and come up with unhelpful things like monad tutorials: https://byorgey.wordpress.com/2009/01/12/abstraction-intuition-and-the-monad-tutorial-fallacy/
Came here to say something similar to this.
There’s so much misinformation by well-intentioned learners.
I’m not trying to diminish the importance of journaling either! Journaling != Tutorials.
Publishing your tutorial gives it an audience, which means someone may (hopefully!) come along and correct you on your errors. This is invaluable.
I also disagree with this negativity. Make it clear at the top of your tutorial that you’re a beginner and you may not have it all right. But with that caveat, publish away.
I think we’re discussing the same thing but disagreeing on the semantics of it.
Absolutely invaluable, but at the very same time, the exposure spreads the misinformation to more readers, potentially doing more harm than good. I don’t think a disclaimer is enough. I think the word “tutorial” implies some authority, unfortunately.
I think a better way is to humbly share a report of your findings so far, with questions and an (as appropriate) admission that you don’t understand everything. Julia Evans is masterful at this style.
As a reader new to the topic, you get the benefit of an explanation of what she currently understands (which is often from a beginner’s mind), and usually some questions to seek answers to on your own. As an expert of the topic, you are invited to share more, or clarify, or correct (and this happens a lot on twitter, and/or HN, etc). But you’re doing so from a place of empathy (you want to be helpful) instead of from a place of disgust (ugh! why is this tutorial so bad!).
I disagree with the negative posts. Writing about something you’ve just learned is absolutely a wonderful way to cement the knowledge, record it as you understand it for posterity if only for yourself, and help you pull others up right behind you. It’s not your responsibility to keep your ideas to yourself until some magic day where you reach enlightenment and only then can convey blessed knowledge on the huddled masses, a lot of this stuff (the specific tech, for the most part) moves too damn fast for that anyway. Maybe we need better mechanisms for surfacing the best information, sure, but discouraging people (yes, even noobs) from sharing what they’ve learned only ensures we’ll have fewer people practiced in how to do it effectively in the future.
That said, I do 1000% agree that people writing in public should be as up front as possible about where they are coming from and where they are at. I definitely get annoyed with low quality information that also carries an authoritative tone.
There’s a world between documenting how you learned a thing, and writing a tutorial for that same thing. If you’re learning a thing, probably don’t write a tutorial. I agree with you, writing about a freshly learned lesson helps in making the learning more permanent, though.
In the case of projects, I’d rather see people committing documentation changes back to the project, at least here the creator of the project can review it.
It’s a free internet and nobody can stop someone from doing this, but, IMO, the problem with technology is not that there is too little poorly written tutorial out there. Maybe it’s worth finding other ways of being constructive.
Writing it down can help the mind remember or think on things. If errors are likely, then maybe they just don’t publish it. They get the benefits of writing it down without the potential downsides.
This is not a good idea. I have looked for documentation on many things that I needed to learn, as you do, only to find that the tutorials/introductory docs didn’t match any of the stated goals or aims of the API. Nothing quite as annoying as realizing the document you’re reading fundamentally misunderstands the thing it’s trying to document.
As mentioned by a few people, there are some flaws in this in what it means for you and your readers following it. Something I’ve considered a worthwhile approach, however, is similar to this.
We have a paired group at university where each week we pair off and learn about a particular subject. Later, we come back together and teach each other what we’ve learned. It’s useful to go head to head on the misconceptions you’ve each picked up, and you can correct and work with each other to both develop a better understanding.
As for me, writing tutorial is not an easy part of learning, especially if you are not pro in area what are you writing about. I would recommend writing a pet project first, share and learn for a community and after that you can write a tutorial :)
Sure, but if you publish it online don’t advertise it around unless you know it’s 100% correct and useful to others.