Writing WordPress Guides For The Advanced Beginner

Advertisement

Creating WordPress tutorials is a fantastic way to help build the WordPress community and to increase your Web traffic. That’s no secret. Just Google “wordpress tutorial” and you’ll see hundreds of results. The complete novice will find scores of well-written tutorials clearly demonstrating the basics of the WordPress dashboard and of activating the default template, in simple jargon-free language.

howtosplash5501

Unfortunately, after the first few “Hello World!” tutorials, they are in for a bit of a learning curve. Suddenly, the guides start to skip a lot of details, assuming that the reader “already knows this stuff.” Others are simply written exclusively for advanced WordPress users.

So, where does a new developer go after square one?

In this article, we’ll explore how to create clear easy-to-navigate tutorials, and tailor them to the underserved “advanced beginner” Web developer. The entire goal of this article is to make sure we see many more tutorials written for budding new coders who are ready to jump to the next level.

Who Exactly Is An “Advanced Beginner”?

Advanced beginners are people who generally understand how WordPress works but don’t fully understand how to implement its concepts. They are stuck in that awkward stage where a “For Dummies” book has nothing new to offer but raw code is still vaguely confusing. In your tutorials, you should strive to eliminate this common “tough it out” phase.

For our purposes, let’s assume that we are writing for someone who has a reasonably good grasp on the following:

  • Can read and write XHTML and CSS, but probably sits with a cheat sheet open to get through those tricky spots;
  • Knows little to nothing about PHP;
  • Can navigate the WordPress dashboard and has basic knowledge of image resizing and editing;
  • Understands the basic idea and principles of WordPress, but not necessarily how to execute them;
  • Appreciates the simplicity of WordPress templates but wants to learn how to create or tweak their own.

Admitting That WordPress Can Be Tough

We all need to stop pretending that WordPress is this magical dirt-simple Web development solution. Yes, using it is much easier than designing a custom CMS, but for new users looking to get under the hood, the tool can still be daunting and complicated.

For the average coder who is still just getting a grip on fundamental CSS, even the strange-looking batch of official WordPress folders that come in the installation ZIP file can be intimidating.

2
This is way more confusing for a beginner than seeing a simple HTML file, a CSS file and some images.

When you refer to a file such as style.css or an image, be sure to tell readers exactly where to look and where to save these files.

Basic Guide-Writing Principles

Before we delve into WordPress-specific tips, let’s go over some basic principles for any tutorial.

Keep It Tidy

Readers have sought your advice because they are confused. Don’t add to their troubles with a cluttered how-to article. Use plenty of bullet points, and keep paragraphs short. If you’re tackling a complex idea, split it up into sections.

Take the format of Smashing Magazine’s articles. Articles are broken up so that each sub-topic has its own section. This simplifies the navigation, makes the content more visually appealing and clearly guides the reader through the process.

Make Sure Readers Are Fully Prepared

Any good tutorial includes all of the resources it recommends. Don’t just say “make a blue image” — give it to them. Otherwise you risk over-complicating things for the reader. Provide sample files, and explain that your lesson will deal exclusively with these readily available resources. You wouldn’t want them to suddenly have to read a Photoshop tutorial when they’re only interested in learning how to customize their header.

3
This tutorial4 includes everything a reader needs to get started, including a visual demo and easily accessible sample files.

Define Your Goal

The best tutorials focus on a single topic. Plan the article before writing it. You shouldn’t explain every aspect of CSS and WordPress on every page of your website. What will readers get from this particular tutorial? A nice neat list at the top of the article should clearly define its parameters.

List the Prerequisite Skills

A tutorial should always list any skills that the reader will be expected to have. Instead of cluttering an otherwise focused guide with extraneous detail, provide links that direct readers to where they should go to learn about particular topics. This will help new developers who are nearly clueless, while keeping the article clearly focused for more advanced readers.

Tips Specifically For WordPress Guides

Now that we’ve discussed some fundamental organizational skills that will make any tutorial clear and easy to follow, let’s delve into some WordPress-related areas that many guides seem to miss.

Taming the Codex

The WordPress Codex is a powerful tool that can give your tutorial a much-needed jolt of clarification. Just be aware that to newbie designers, the Codex can seem like a massive labyrinth of articles, with each topic requiring that you read several earlier lessons in order to fully grasp. As the experienced coder, you need to show that, when used properly, the Codex presents the cleanest example of a concept.

5
The Codex6 is one of the most useful tools available to a WordPress developer.

Don’t just say “Check the Codex” and drop in a link. Your readers need context. Your main goal in writing a tutorial that refers to the Codex should be to eliminate the reader’s need to plunge into its depths. Tell them what they can expect to read on the page, illustrating exactly how they can use the particular lesson you’re linking to.

It might even be to your benefit to point readers to a “beginner’s guide” to understanding the codex. Here is my favorite.7

Keep Them On Target, Visually

The most important thing to do to keep readers on track is to provide constant updates throughout the article on what they should be seeing in their own implementation. For example, if your tutorial is multiple pages, always start with an illustration of the finished product. After each milestone, provide a “Here’s what you should be seeing right now” example. Whenever possible, include working samples of the project or its parts for the reader to experiment with. (These functional samples might have to be run from the author’s server or a third-party website.)

A WordPress project could very easily require coding between a few files. If someone isn’t following closely enough, they could miss something simple that wildly alters their results. Your milestone examples will give readers up-to-the-minute feedback on where they are going wrong. It’s the best way to make sure you aren’t losing anyone.

Make Your Code Selectable

This is crucial to any WordPress tutorial. If you are explaining a concept in code, allow the reader to copy and paste the examples whenever possible. For curious readers, nothing is worse than wanting to test a sample line of code, only to realize that they have to fully type it out. This principle seems self-evident, but many guides simply explain an idea and say, “Add this code,” alongside a screenshot of the finished style sheet. If the reader misses one semicolon, all their work will be worthless. That’s infuriating.

While there may be some merit to having the reader actually write out the code, most people probably won’t see it that way. They are much more likely to seek out another tutorial, one that doesn’t force them to constantly rewrite code that they don’t yet understand.

Be Wary of PHP

While it’s a necessary part of WordPress, remember that to someone just getting their footing with something as relatively basic as CSS, PHP code can look like someone fell asleep at the keyboard. Too many tutorial providers assume that their readers understand even the first thing about PHP. This is often not the case.

In the likely event that you are explaining low-level PHP to readers, be mindful that they might be confused. Give a short description of exactly what is happening in the code. As always, provide a link to a relevant PHP tutorial.

Clarifying Custom Widgets

Admittedly, this recommendation is pretty specific, but bear with me. When I was getting started, one of the most infuriating things about WordPress tutorials was when they said, “Write a quick widget with this code…”

Now, once a reader has created their first widget, it becomes completely obvious that most of the time all they’ll need to do is drag the “Text Widget” and add some basic HTML code to it. But first they need to get past this initial step. Remember that to someone looking with fresh eyes, they may not understand your shorthand.

8
The blank text widget is a simple yet potentially deceptive name for a powerful tool.

So, I always like to see a description such as, “Use the ‘Text’ widget to create this option. You can simply add raw HTML into the blank box and drag it to your sidebars. This will then work just like any other widget.”

Always Provide Documentation for Video Tutorials

Without a doubt, video is a massive help for confused developers. It provides detail-rich, play-by-play instruction that carefully guides the viewer through the concepts in the tutorial. Just be sure to accompany the video with detailed textual documentation. Otherwise, people will repeatedly have to rewind and squint at the screen just to copy your instructions. That’s an easy way to lose fans.

Treat the video as an aid, not as the main event. This tutorial on Lifehacker9, though not specifically for WordPress, illustrates this principle perfectly.

Update Your Tutorial As Needed

Keep your guides relevant and dynamic. Too often, tutorial writers will clarify major points in the comments section of their page, while the tutorial itself remains static. Or they just ignore the page entirely, leaving now-irrelevant guides to linger on the Internet.

Keeping in touch with your audience is wonderful, but giving new readers the best possible experience is also important. Don’t expect people to comb through two years’ worth of comments to find your changes.

Make sure your supplemental links remain relevant. Nothing is worse than reading a tutorial from 2007 and seeing the words “With a simple change, it should look like this10!” Surely in 2007 that link was perfect, but if it leads to an unrelated page in 2011, it will undermine your entire article.

Tell Them Where to Code

Make sure that newbies are tweaking code in the right place. Point out that, in general, they shouldn’t edit files from within the WordPress dashboard. That leaves little room for error, and if the coder isn’t careful, they could lose hours of progress.

11
A brief glimpse at the SFTP- and FTP-enabled one-stop code editor, Coda.

Instead, teach them to use an SFTP- or FTP-enabled editor, such as Coda12 or Dreamweaver13. It’s a safer, fixable way to correct any mistakes that arise.

Teach Them How to Test

This last point is just a personal preference that I wish more people would do. One of the best things about basic HTML and CSS is that you can easily test them locally by simply reloading the browser. When you jump into WordPress, this testing process becomes significantly more complicated. Advanced beginners will likely be lost once they realize that they can’t test by simply dragging their WordPress creations into a browser. This leads many new coders to test their unfinished creations on production websites.

Tutorial writers should stress the importance of not testing WordPress changes on a live website. Explain the myriad benefits of designing on a risk-free local server. Just point the reader to one of the many existing server guides, and briefly mention the pitfalls of testing code on a live website. Michael Doig’s article “Installing WordPress Locally Using MAMP14” is one of the most useful set-up guides.

Conclusion

Whether you’re writing a tutorial about WordPress or anything else, clarity is paramount. Put yourself in the reader’s shoes. WordPress is built on the efforts of a wonderfully helpful community that is full of excellent tutorials and experts. But, as in any community, this has resulted in some confusing jargon and common shortcuts.

These can overwhelm new developers. Tutorial writers should avoid unnecessary jargon and always explain any references and functions that they use, no matter how basic they seem. Remember that, as the guide, your knowledge is likely far beyond that of your readers. What is obvious to you could be brand new to them.

By making your tutorials easier to understand, you’ll greatly increase your own Web traffic and enrich the greater WordPress community.

Other Resources

Here are a few tutorials that are easy to follow and that adhere to many of the points mentioned here.

(al)

Footnotes

  1. 1 http://www.smashingmagazine.com/2011/11/08/writing-wordpress-guides-for-the-advanced-beginner/
  2. 2 http://www.smashingmagazine.com/wp-content/uploads/2011/10/wpfiles.png
  3. 3 http://net.tutsplus.com/tutorials/wordpress/how-to-create-a-wordpress-theme-from-scratch/
  4. 4 http://net.tutsplus.com/tutorials/wordpress/how-to-create-a-wordpress-theme-from-scratch/
  5. 5 http://codex.wordpress.org/
  6. 6 http://codex.wordpress.org/
  7. 7 http://lorelle.wordpress.com/2005/10/28/a-guide-to-the-wordpress-codex-the-online-manual-for-wordpress-users/
  8. 8 http://www.smashingmagazine.com/wp-content/uploads/2011/10/textwidget.png
  9. 9 http://lifehacker.com/5790955/how-to-make-a-web-site-the-complete-guide/
  10. 10 http://www.example.com/
  11. 11 http://www.smashingmagazine.com/wp-content/uploads/2011/10/coda.png
  12. 12 http://www.panic.com/coda/developer/
  13. 13 http://www.adobe.com/products/dreamweaver.html
  14. 14 http://michaeldoig.net/4/installing-wordpress-locally-using-mamp.htm
  15. 15 http://webdesignerwall.com/tutorials/complete-wordpress-theme-guide
  16. 16 http://lifehacker.com/5790955/how-to-make-a-web-site-the-complete-guide
  17. 17 http://wphacks.com/sliding-doors-wordpress-navigation-css-technique/
  18. 18 http://michaeldoig.net/4/installing-wordpress-locally-using-mamp.htm
  19. 19 http://net.tutsplus.com/tutorials/wordpress/how-to-create-a-wordpress-theme-from-scratch/

↑ Back to topShare on Twitter

I’m a web, social media and SEO publicist for several consumer electronics companies. Additionally, I write tech and video game news and reviews for Newegg.com’s official blog and several other outlets. Follow me on Twitter @scottmeaney.

Advertising

Note: Our rating-system has caused errors, so it's disabled at the moment. It will be back the moment the problem has been resolved. We're very sorry. Happy Holidays!

  1. 1

    I completely agree, too many tutorials out there which copy this huge piece of code and paste into a file called X.

    I’ve started a series on wptuts which tries to approach theme dev training in a step-by-step approach – http://wp.tutsplus.com/tutorials/wordpress-theme-development-training-wheels-day-one/

  2. 2

    Thanks for the reminder. It’s easy to forget what it’s like not to know something, and the effort it required to learn.

    I think a lot can be said for including good links to pages that clarify anything that might be hazy to someone, allowing them to go and catch up before continuing.

  3. 3

    For video tutorials: make sure that the voice recording is as loud and as clear as it possibly can be.

    Mega bonus points for adding captions, even at a later stage.

    Examples:

    1. I’ve reluctantly had to pass on purchasing Mark Boulton’s excellent video tutorials, “Designing Grid Systems for the Web” (fivesimplesteps.com/products/grids) because I can only make out 2 words in 10 (it’s recorded in a classroom situation).

    2. The O’Reilly webcasts (oreilly.com/webcasts/index.html) (free but intended to promote new books) are of very varying quality. Yesterday’s hour long webcast on Applying Patterns to Mobile Design had Steven Hoober speaking on a megaphone at the bottom of the ocean. At least that’s what it sounded like. I tried desperately for 20 minutes to make out what he was saying because the slides were so good and I intended buying the book but it was just impossible to hear anything so I gave up.

    Video/audio content providers: it’s not just those of us in the deaf and hard of hearing community who need captions! Captions = purchases!

  4. 4

    Nice to know that SM have great WP articles now… But… Why they are directed to Content Writers instead of Advanced Beginners?

  5. 5

    You should add as well that all code should follow the WordPress Coding Standards and that the Inline Documentation is of high importance…

    http://codex.wordpress.org/WordPress_Coding_Standards
    http://codex.wordpress.org/CSS_Coding_Standards
    http://codex.wordpress.org/Inline_Documentation

    …which sadly, since they’re both well written and documented, isn’t the case in most cases (e.g. http://bit.ly/vNewy6, http://bit.ly/v9pH1d, http://bit.ly/sxinDl, http://bit.ly/temVkp and http://bit.ly/vcMNPM).

  6. 7

    The biggest barrier I had to learning WordPress was getting xampp working. Then I found out about InstantWordPress (here: http://www.instantwp.com/). It’s really easy – I downloaded and installed it, and had a working instance of WP up, ready to work on, in less than 7 minutes.
    I know xampp works great for lots of people, but if anyone is having trouble with it, they might want to give InstantWordPress a try.

  7. 8

    I will be sure to make use of the resources shown here on my new wordpress blog.

  8. 9

    Great information.Its realy useful for beginners.Thank you for sharing.

  9. 10

    I bet dropping a tutorial would bring some traffic and loyal audience. Anyone tried this technique ?

  10. 11

    Thank you. I’m the “advanced beginner” who is looking for more tutorials and it’s great to see an article being written about what us advanced beginners need.

  11. 12

    Thank you for this article! I fall into this category of “advanced beginner” (I know the basic components of a theme, but I’m still testing CSS code in production sites) and I’m definitely going to check out the links you recommended.

  12. 13

    Super article!

    This is an issue in almost any field.
    There are four stages of development for learning any new skill. I started to tag my videos based on the four levels that I have seen and in my own experience with learning WordPress.

    I listened to the State of the Word from the San Francisco WordCamp and Matt talking about the WordPress New User eXperience (WPNUX) and I came up with these four stages.

    NOVICE
    One who has a little information but needs the tools, skills and knowledge to understand and apply this information. It is not assumed that they know the terminology or concepts. They may not even know how to ask a question or use the correct wording to get a sufficient answer. May visit a support site but does not ask questions.

    BEGINNER
    One who has a general knowledge of the material but still has difficulty with the tools and makes mistakes. Has difficulty completing a task even with step-by-step instructions. Somewhat familiar with the terms and concepts but still needs very detailed information. May visit a support site and ask questions and them ask for clarification or more instruction. May seem to be frustrating to deal with at times.

    OPERATIVE (Advance beginner in article)
    One who has the tools and information and can use then with some effort and assistance. Can follow step-by-step instructions to complete a task. Able to give information to others but may not be able explain it adequately. May visit a support site and even give advice but it may not always be complete.

    EXPERT
    One who has the tools and information and is comfortable with them and can apply them to the task at hand with ease and can explain the task for someone else to follow. May visit a support site and give advice. May even be a moderator for the site.

    I am now using a flag to tell anyone interested in the video what to expect based on these four levels.

    Michael

  13. 14

    Nice information.Its really useful for beginners.Thank you for sharing.

  14. 15

    Thank you, thank you, thank you. I am an “advanced beginner” and feel like I have fell in the WordPress crack somewhere. This post is exactly what I was looking for. You have described my wife and I to a “T”.

    I appreciate you taking the time to write this article.

    thewpnovice

  15. 16

    Nice article

  16. 17

    I would like to know some useful strategies to display the code in my wordpress tutorials, how to style just the code so that the use can easily copy- paste it. can you do a wordpress article on how to handle the technical aspect of writing tutorials?

  17. 18

    This was by far the best article I have seen online yet! I don’t know how many hours I have spent struggling to keep up with tutorials on WordPress only to have 50 bookmarked articles and no real work produced from it. I hope that everyone takes your advice on teaching on the web to new developers.

    One day when I am a decent enough designer I will remember this before making my first article.

    THANK YOU!

  18. 19

    the link :
    http://net.tutsplus.com/tutorials/wordpress/how-to-create-a-wordpress-theme-from-scratch/

    dont work anymore since a long time…. i send a mail, but i think they really dont care about it….very serious.

↑ Back to top