Authoring Introductory Articles
Just finished replying to an author who asked me to review his introductory article.
The lesson learned from reading and reviewing is that there are some quite common pitfalls to these kinds of articles, which are essentially the same thing:
Thinking That One Size Can Fit All
You are writing an introductory article, so, you target beginners, but even for beginners, you have to assume some level of common ground as a foundation to build on, but how much of a common ground is that? IS the author targeting those who have experience with similar tools/concepts? Students? Professionals with other (unrelated) programming experience?
Sometimes it feels like the author keeps changing his imaginary idea of the intended audience as they keep writing. Eventually the author finds himself inserting some hints and references that if the reader understands then they probably don’t need to read your article (except to review it).
Which leads to:
Unlearning is hard
Just simulating not knowing what you know already. Yes, it’s not that easy!
If you are an author
When you work on any kind of introductory material (which is different from these posts you write just because you want to “take the thought off your chest to the wild”), always be very strict about:
- Who you audience are
- Who your audience are not
Identify them by what they do, and what experience they had doing what they do. Be honest with yourself about this identification means they’ll actually benefit from your material or they’ll just congratulate you on it (if you know some people who fit into the audience) without real benefit.
Think of what they are “not” more often as you keep writing. Check every assumption about the audience that you make in the material against the “not” bit.
You may find it hard. Depending on why you are working on the educational material, it may simple be worse changing the intended audience. If this happens without lots of modifications to the work you already did still, it means neither of your images about the intended audience were correct, not the original one, and not the new one too.
As A Reviewer
A reviewer also has their own challenge…
10 lines of code = 10 issues. 500 lines of code = "looks fine." Code reviews.
— I Am Devloper (@iamdevloper) November 5, 2013
P.S. Please help me out by checking this offer, then look below for a small Thank You.
How did I learn that?
As a bonus for coming here, I'm giving away a free newsletter for web developers that you can sign up for from here.
It's not an anything-and-everything link list. It's thoughtfully collected picks of articles and tools, that focus on Angular 2, ASP.NET 5, and other fullstack developer goodies.