How To Make A Great WordPress Tutorial

A very cute photo of a Lemur
The WP Crowd

Josh Pollock

Published: May 18, 2016

Recently my friend Matt and I were talking about writing blog posts. We talked about structure, form and keeping ourselves motivated to get a post completed. I write a lot of blog posts and I have a lot of friends that do too, but I can’t remember ever having a talk like this about the craft of blogging. Not just the craft of the blog post, but the craft of the WordPress tutorial blog post.

Sure, I read tons of articles on why you should be blogging, and content strategy and SEO, but never on the craft of writing these posts. Writing is a craft, and it takes practice, education, and experience to do well. Writing technical articles about WordPress that are engaging, easy to read and motivate the reader to actually try what is being described isn’t easy.

This type of article, the “WordPress how to” is a unique subset of the blog post genre. It’s actually an incredibly popular one that I think is worth some examination. In this post I want to share some insights in the process. I hope it will motivate you to think more about your writing process and take the time to improve it.

Make Your Purpose Clear

In my last post for The WPCrowd I wrote about crafting a strong introduction and conclusion for a technical blog post. I don’t want to reiterate too much. But, my biggest take away was not to be afraid to tell people what you are teaching them and why. Say it when you start, repeat it at the end.

Seriously, don’t forget to explain why. A technical blog post is selling a solution, but you can’t do that without making a problem clear.

Know What You’re Doing On Your Way In

I write really fast. I recently wrote seven thousand words worth of technical tutorials and a post on WordCamps in about six hours and that includes two breaks for food. I can do this because I can see the whole post in my head before I start.

When I was in grad school I got very into outlining everything before I wrote. It was a really essential process in figuring out how to explain things clearly and logically, which was not a skill I had previously possessed.

I don’t outline my blog posts anymore, but I used to and I recommend it. If you’re going into a post with little idea of what you’re going to cover and how it is going to flow, you’re not setting yourself up for success.

Not everyone has to be fast. I like to troll my friend Carl about how much more content I generate then him. But, it wouldn’t be a #carl2016 article if it didn’t have the kind of detail and depth that a Carl Alexander article has.

Be Safe When You Go Epic

A cute photo of two lemurs hanging out.Sometimes you can get your point across in less than a thousand words. I’m pretty in awe of how Tom McFarlin has been making shorter posts that are just as useful and impactful as his posts have always been.

That said, sometimes you’ve got to go long. An epic post is hard. Proper planning is a must. But also, consider that a series of shorter posts is best. When I used to write for Tuts+ I planned out a lot of long series because the way they paid authors really encouraged doing it that way. Also, as you probably know Tuts+ is all about series of posts.

Writing a series not only helps you break down your work into smaller chunks, but it also makes it more approachable. The cross-linking, and having multiple meta descriptions, which are more specific, is also good for SEO and making your post more discoverable.

It’s hard to know when one giant post is better than a series, but what’s most important is that you get it done. If a series makes you less stressed and brings the writing out easier, do it.

Keep Coming Back To Why

Writing a long technical blog post isn’t easy. Keeping yourself on track is hard. When you keep bringing the narrative back to why the topic is important, it helps you keep yourself motivated. It also helps your reader track what you are trying to say.

You don’t just want people to read your tutorial, you want them to be motivated to try what you are writing about. This is why you need to keep bringing them back to why your topic is important. It also really helps in bridging each part.

For example, if you were writing about customizing single post views in themes, you might start a section on author meta information like this:

When I started this post I said that it’s so important to make sure that you highlight the parts of the page that advance the strategic marketing goals of your site. If a blog is about providing the expertise of the author or a company’s staff, drawing attention to the author’s bio ensures that readers know who the expert they just learned form is.

Yes, this approach leads to repetition, but that’s OK. People need be reminded what the point is and to be constantly motivated to succeed.

Don’t Be Too Specific

When you write technical documentation you have to be very specific, but a WordPress site, plugin or theme isn’t a piece of furniture. There is only one way to assemble a desk properly, but everyone uses WordPress differently.

When you get too specific the less you are teaching a concept and the more you are teaching a rote process. WordPressing isn’t a skill that can be learned by rote. WordPress sites are unique, ever-changing assemblages.

Too much precision isn’t just dangerous, it’s tedious. It makes the writing process boring, and your reader will feel that.

It’s About The Journey

A technical blog post is a story in which the reader is the hero. We don’t think about posts that way too often, but we should. Without a narrative thread, you just can’t tell a compelling story, it’s how human brains work.

If you want to write well, study the concept of the hero’s journey. It’s fun, you get to think  about Star Wars and Lord of the Rings.

The basic thread of every good tutorial should be: “you wanted to do this thing because it’s important for X reason. Then I showed you how to do it. Now you can know how to do it, and will do it because it is important for X reason.”

Read, Practice and Repeat

An incredibly cute photo of a lemur with a baby lemur riding on it.Writing isn’t easy. The only way to get better is to do it regularly and read your writing and others critically. Find technical writers that you like that are great and think deeply about what makes their writing so useful to you.

I also am pretty sure that my technical writing is better when I’m reading really good hard sci-fi and/or cyberpunk books. I just finished reading six Expanse novels and besides enjoying them, I believe it helped me improve my technical writing. I’d have to do more research for sure, but I think that William Gibson’s sprawl trilogy, starting with Neromancer, is probably some of the best books to read in order to increase your technical writing skills.

What’s important is that you keep yourself motivated to not only finish an article, but be excited by it the whole time. Take care of yourself friends, your readers can tell if you’re excited about a topic or bored by it.

When I talked to Matt the other night about writing, I didn’t have any simple answers for him. Writing isn’t easy. But I think that by making sure you keep coming back to why, and have a clear path through an article that you’re constantly reminding yourself and your readers of, that with practice you can be awesome at sharing what you know.


All images of Lemurs are from WikiCommons and are very adorable.

Get the latest from The WP Crowd

Leave a Reply

2 Comment threads
0 Thread replies
Most reacted comment
Hottest comment thread
1 Comment authors
Bridget Willard Recent comment authors

This site uses Akismet to reduce spam. Learn how your comment data is processed.

newest oldest
Bridget Willard

I never find writing easy. But once I outline it in my mind, I’m usually okay to go.

Bridget Willard

I never find writing easy. But once I outline it in my mind, I’m usually okay to go.


In theory yes, but I think it can only apply to some websites, and might have bad knock-on effects with other peoples plugins.

If your site is closely under your control then I think you can, if you rely on anyone else’s code then you are at risk of getting spurious errors/problems.

I really considered this when making this post, and also seeing what transients might mean to the equations, but the variables are too great to give sound advice.