A tutorial on creating coding tutorials

So you’ve just implemented an offbeat and interesting solution to a particular coding problem. You’re pumped. You decide to create your own tutorial to pass along your knowledge to the rest of the world.

You dream of hundreds of comments and thousands of retweets because, after all, it’s the unicorn solution every developer has been looking for. It’s the next clearfix and responsive design, all rolled into one, only much better and smarter. It might even get retweeted by Jeff Zeldman or Jen Simmons!

But it probably won’t.

The reality is that the internet is saturated with tutorials. Readers have short attention spans, often skim articles, and if the first few sentences don’t hook them, they’re moving on. We’re lucky if readers get past the first paragraph before scrolling down or fast forwarding to look for a code snippet to solve their problem.

Heck, you may have already given up on this post.

As tutorial creators, it’s our responsibility to provide a problem and solution for our readers in a unique and clear fashion. As an avid consumer (and sometimes writer) of coding tutorials, I’ve seen the good, bad, and the ugly. I’d like to share, in no particular order, some pathways to success when forging ahead on your next tutorial.

Just a quick note: I’ll use article and tutorial interchangeably to refer to either a coding article or video. The following sections refer to both, with the exception of the writing specific parts, of course. For simplicity, I’ll refer to readers and viewers (of videos) as just readers.

A few notes on writing

Never publish a first draft, even if you think it’s flawless.

It’s not.

The best advice I ever received was from my cousin, a writer, who told me to put aside first drafts for at least a week before looking at them again. At first, I thought this advice was counterproductive. Won’t this interrupt my flow? Won’t my ideas suffer? But when I came back a week later with fresh eyes, I noticed glaring mistakes that I wouldn’t have been able to fix because I was blinded by the false glow of my shiny perfect first draft.

You can’t get to the truly great ideas until you get through the bad ones. The problem is we think our original ideas are the best ones, and we hold onto them like a lifesaver.

But they’re not; they only lead us to the real piece.

The same principles should be used when writing coding tutorials. And if you’re on a deadline and can’t afford to set aside a week or two, even setting it aside for a few days will make a big difference.

If you never give yourself space from your draft, you’ll be stuck in Firstdraftland™, a place where stubborn thought processes and ideas refuse to grow.

While a coding tutorial is not the next great American novel, writers should also pay particularly close attention to proofreading and grammar. This sounds obvious, but I’d venture to say that at least half of the articles I read have some serious issues from a writing standpoint. Grammatical mistakes are distracting and make you lose credibility. Before sending an article out into the void of the internet, spend a day proofing.

Structure

Coding articles tend to be short, but they should still be treated as a novel or short story, with a beginning, middle, and end. The first section should describe the problem/topic and your proposed solution. If your tutorial is long, this is a good place to lay out a roadmap or table of contents for the reader.

Grab the reader’s attention here, because you only have a few sentences. It’s okay to give a little fluff in the first paragraph about why you’re writing the article or how you almost quit coding before you solved this issue, but don’t get into a meandering narrative about your life.

I’ve read so many articles where the first six paragraphs/minutes are about the author, their background, and a deep dive into their coding philosophy. As my grandma used to say when someone was long-winded, “Turn the page,” and get to the meat of the article.

The second section should be the reason you’ve created the tutorial, the actual tutorial, which we’ll get to later, while the third section should wrap up what you’ve taught with any possible links to further study.

Audience

Before you type a word, first decide on your audience.

Are you writing for developers familiar with the topic? New to the topic? Experienced JS developers? Figure this out and stick with it for the entire article. Focus. How many times have you viewed a tutorial about, for example, Redux, where the author will spend half the time explaining HTML?

On the flip-side, when I was first starting out, I remember a tutorial about an introduction to HTML and CSS where halfway through, the author started discussing AJAX and other advanced concepts that were way over my head at the time. It’s important to stick to your audience, otherwise, readers will get frustrated and/or bored and move on.

Some do’s

Show before tell

Before getting into the meat of the tutorial, don’t forget to show your readers the end product. Even if it’s a simple tutorial about centering text using flexbox, link to a codepen so the reader has some context around the code you’re about to explain. And don’t be afraid to get creative with the example, even if it’s simple.

For me, I have trouble understanding articles where the author doesn’t show the end result from the start, and I usually have to reread the article afterward once I see all the code.

It’s a tutorial — make sure the code works

This leads to my next part. Make sure your code actually works! There are lots of articles claiming to solve a problem, but when they’re actually implemented, they don’t work, wasting the readers time.

Start small

When you’re laying out new concepts to readers, start small, then work up to more complicated examples. If you’re introducing something like Redux, use a simple example at first, like updating a list of posts. Don’t jump into a complicated example using OAuth.

I see so many tutorials claiming to explain a concept to someone who has never used it, only to get halfway through the article and scratch my head because I’m confused or can’t follow the thread.

It’s easy to forget that your reader, presumably, has never worked with what you’re explaining. Otherwise, they wouldn’t be reading your article in the first place.

Write beyond the documentation

When writing about a particular topic, don’t just copy the docs. If I’m reading the tutorial, it’s safe to say I’ve already read the docs and I’m still confused. As a tutorial writer, it’s your job to expand on, not regurgitate. And in order to prevent redundancy, you should actually read the documentation for yourself as it will make the tutorial much better.

Keep the code blocks to a minimum

No one wants to read a 75-line code block. If your code block can’t fit within the view height of the screen, consider breaking up the block with explanations in between to help the reader better understand your code. Nothing will scare a reader away faster than a behemoth code block.

Write what you want

While writing a novel or a screenplay, you can’t really predict what the world will latch onto and what they’ll toss aside. Today might be dystopian thrillers, but tomorrow could be a resurgence of 1990s style action movies. When writing on the trends, you end up writing one of those bad vampire movies that came out after Twilight.

This should be no different with tutorial writing. Write from your experience, and more importantly, write what you want to write. If this means writing about your passionate support for bringing back the <blink> tag, then make it happen.

Well, actually, don’t do that.

One of your jobs as a developer is to stay up on the latest trends, but you get my point. Following your gut will make your tutorials feel more authentic and knowledgeable.

Memes and “humorous” GIFs

While I love a good GIF as much as the next person, I’m not quite sure how they ended up being peppered into two-thirds of the tutorials on the internet. To me, they are incredibly distracting, and personally make me a little nauseous when they loop over and over again. But if you really need to include them, make sure they are adding value to your tutorial, not just comic relief.

Some don’ts

In the meat of your article, use real-world examples. Please, for the love of God, do not use the dreaded foo, bar, and bazz. When we use foo, bar, and bazz, our examples lose all meaning, even if it’s just one line of code. If you’re explaining an association, what is a foo? How does it relate to a bazz, and how do those relate to a bar? I’ve seen multiple attempts at using foo, bar, and bazz to explain Redux, and I have to say, you’re better off not even reading the article. If I click on an article and see foo, bar, and bazz used, I immediately move on to another article. Maybe this is harsh, but it’s true.

Use words with real meaning, like blog and posts or feed and tweets. I see so many tutorials use foo, bar, and bazz, and they only confuse and force the reader to spend wasted time figuring out how they relate. Unfortunately, this sickness has reached epidemic proportions. If you take one thing from this article, follow this rule.

Your ego

Remember, you’re here to teach.

Developers are (usually) smart and possess skills that few people have. Most people don’t understand what we do, but they’re impressed by our knowledge. My brother once relentlessly kept asking me how the code I write gets compiled down into ones and zeros, to which I actually didn’t have a great answer for him.

So, okay, maybe we don’t know EVERYTHING.

But I notice in many articles, the author spends more time trying to sound smart than actually teach something. As tutorial creators, it’s our job to check our egos at the door and focus on helping our readers understand code instead of putting our knowledge on display. I don’t think it’s deliberate, but there is a tendency for some authors to place more emphasis on their own skill instead of passing information along in a clear and concise way.

Fear

Don’t be afraid to create a tutorial. The dev world is competitive and can be snarky. It’s easy to get imposter syndrome and believe you’re not good enough, even if you’ve been at it for years. It’s also easy to get intimidated because it seems like everyone writes more elegant code than you, which can make some people hesitant to try and pass their knowledge along to others.

If we view our articles from the standpoint of helping people, as service, instead of worrying about how other developers will judge us, we’ll all be better off. In the end, even if you only help one person learn something new or solve a coding problem, you’ve succeeded.

Etiquette

To wrap up, I’d like to talk about etiquette. When we have a problem that can’t be solved by an article, a good option is to scour or post on a site like Stack Overflow. These sites can be very helpful, but if you’ve spent any amount of time on one, you’ll know you’ve entered into a minefield of callousness. Let me help you navigate.

If you’re posting a question, make sure you’re clear on what you’re asking. In fact, make sure you end your post with an actual question that starts with, “How do I…?” Be sure to post any code you’ve attempted, but don’t post unnecessary code or you’ll anger the masses.

If you’ve ever posted a question incorrectly, or not been clear enough, you know what happens. Someone will inevitably post, “What IS your question??” even if it’s clear what you’re asking, then you’ll usually be lectured on posting a question, followed by several posts linking to another question that is similar but not super helpful.

Once this initial wave hits, a feeding frenzy of developers ends up fighting amongst each other. Like male pigeons trying to woo a female, they all flutter their wings and puff themselves up while trying to one-up each other in hopes that they will get picked as the best answer.

If you’re answering a question that’s not properly asked, but you can figure out what the person wants (and most of the time you can) don’t be passive aggressive. Just answer the question.

In an open source environment (or any environment, really), it’s important not to, well, be a jerk.

Fight the temptation to one-up other developers. If you truly have a better solution, great, but don’t berate the previous answer because yours is better. If you want to argue with other people, that’s why they invented Twitter. Let’s try our best to keep it civil, especially when helping out new developers. Otherwise we might scare away some future talented devs.

Conclusion

I encourage all developers to give tutorial writing a try. The more knowledge out there, the better. And if you’re not sure about writing, read as many articles as you can and really think about what made it good or bad and apply those observations in your next article. Keep in mind how hard it was when you first started coding, and think about how we can be of service to new developers.