Writing WordPress Guides For The Advanced Beginner

January 24th, 2012 tWP Plugins 30 Comments
Writing WordPress Guides For The Advanced Beginner

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.

howtosplash550

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.

[Editor's note: Have you already got your copy of the Smashing Book #2? The book shares valuable practical insight into design, usability and coding. Have a look at the contents.]

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.


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.


This tutorial 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.


The Codex 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.

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.


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 Lifehacker, 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 this!” 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.


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 Coda or Dreamweaver. 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 MAMP” 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.

Source: http://wp.smashingmagazine.com/2011/11/08/writing-wordpress-guides-for-the-advanced-beginner/

 

Create Perfect Emails For Your WordPress Website
How To Improve Your WordPress Plugin’s Readme.txt

About admin

» has written 52 posts

30 Comments

  1. Writing WordPress Guides For The Advanced Beginner : dot Key Plugins I was recommended this web site by my cousin. I’m not sure whether this post is written by him as nobody else know such detailed about my problem. You’re amazing! Thanks! your article about Writing WordPress Guides For The Advanced Beginner : dot Key PluginsBest Regards Craig

    • Michael says:

      I will add this tutorial soon.In the aitnmeme, try these instructions:Create the page you want to use as your main page. Also create another page you want to use as your blog page. Now, in the Dashboard, go to Options > Reading.Under Front Page select Front page displays a static page . Now select the page you created for your main page ( Front page ). And select the page you created for your blog page as your Posts page . Click Update Options . That’s it.

      • Dayane says:

        I’ve enabled this and used your stietngs (even though there is a newer version than this available now) and have adjusted my Home Title / Home Description etc and hit update but my title is still what is was before. Any advise?In case it makes any difference I am using a Mac, with MAMP.Thanks

  2. invest liberty reserve says:

    I am not sure where you are getting your information, but great topic. I needs to spend some time learning much more or understanding more. Thanks for great info I was looking for this Writing WordPress Guides For The Advanced Beginner : dot Key Plugins for my mission.

    • Ali says:

      hello , my name is Richard and I know you get a lot of spammy conmemts ,I can help you with this problem . I know a lot of spammers and I will ask them not to post on your site. It will reduce the volume of spam by 30-50% .In return Id like to ask you to put a link to my site on the index page of your site. The link will be small and your visitors will hardly notice it , its just done for higher rankings in search engines. Contact me icq 454528835 or write me tedirectory(at)yahoo.com , i will give you my site url and you will give me yours if you are interested. thank you

      • Shiera says:

        Hey Phil,Yeah, this tutorial was ceeatrd almost a year ago when the gallery feature came out back then Matt didn’t have the tagging stuff up on his site. It’d be a fun project to add that though! I’m not sure what you mean when you say the galleries aren’t implemented into the search I can search for certain words and if the gallery post has that information it comes up. Unless I actually had tagging information like Matt’s site, I’m not sure what information there is to search on.

    • Deden says:

      Lisbeth November 9th, 2011 3:32 am For video tutorials: make sure that the voice dcoerring 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!

  3. I’m not sure where you are getting your info, but good topic. I needs to spend some time learning much more or understanding more. Thanks for fantastic information I was looking for this Writing WordPress Guides For The Advanced Beginner : dot Key Plugins for my mission.

    • Honnyy says:

      It’s standard pitacrce to release an ebook version of all new friends of ED titles. I suspect the reason there’s no link on the yet is because the official publication isn’t due until 1 December. I know that it’s definitely being released as an ebook, so it’s just a matter of time.FWIW, I agree that the book is a bit of a monster to carry around. I originally proposed two separate books, but my editor thought more people would prefer it as a single volume. Producing two books is more expensive, so the cost is reduced this way, albeit at the expense of convenience for carrying around. If you’re based in the United States, you might also be interested to know that all Apress/friends of ED books are gradually being made available in Kindle editions, too.

    • Jerome says:

      The app delegate is layaws available to you. But that’s probably not the best thing to use anyway. Where do you want to save the data to? have you taken a look at the core data and plist tutorials? I’m happy to help, just need to know exactly what you are trying to do. And you can send the code to my email if you want, just give a little explanation of what you are trying to accomplish.kent@theappcodeblog.com

  4. I am not sure where you’re getting your information, but great topic. I needs to spend some time learning much more or understanding more. Thanks for great information I was looking for this Writing WordPress Guides For The Advanced Beginner : dot Key Plugins for my mission.

  5. I’m not sure where you are getting your information, but good topic. I needs to spend some time learning more or understanding more. Thanks for great information I was looking for this Writing WordPress Guides For The Advanced Beginner : dot Key Plugins for my mission.

    • Deniz says:

      Hello my friend!Now I am filanly done with my own galleries, or actually they have been done locally for a while, but after having some problems with my webhost, I haven’t been able to upload the new stuff until now. The guide worked out perfectly for me, accept for one little thing. I had a problem with this line:preg_match(“/.*(/wp-content/uploads/S+.S+)/”, $img_url, $matches);which I had to replace with:preg_match(“#.*(/wp-content/uploads/S+.S+)#”, $img_url, $matches);Since it otherwise interpreted the next / wrong. Don’t ask me why, I found the solution by googling, but I guess maybe you know the answer anyway I also have a request:The images on the show full (medium) image-page links to the next image when you click it. So far perfect! The problem is, when you come to the last image, it would be great if it could start from the beginning again, instead of just jumping to the previous image. This maybe isn’t such a big problem, but if you manually change the order the photos should be displayed, so that the last attached image (highest attachment id) maybe ends up somewhere in the middle, it doesn’t work anymore, since you won’t come to the next photo from there. I hope you understand what I mean!Anyway, if you want to check out the result, go to jensfilipsson.com/category/photo-album/Thanks for your help, a great guide this, a great guide indeed!// Jens.

  6. Nice blog! Where did you get that awesome layout?

  7. Full Article…

    [...]An outstanding share! I have just forwarded this onto a co-worker who was doing a little homework on this. And he actually ordered me lunch because I stumbled upon it for him… lol. So allow me to reword this…. Thank YOU for the meal!! But yeah…

  8. Attractive portion of content. I merely stumbled upon your weblog and in accession capital to assert that I get in fact loved account your weblog posts. Anyway I will probably be subscribing to your augment and even I success you get admission to constantly quickly.

  9. I’m really impressed with your writing skills as well as with the layout on your blog.
    Is this a paid theme or did you modify it yourself?
    Either way keep up the excellent quality writing, it is rare to see a nice blog like this one today..
    Best Regards Shane

  10. micro lan says:

    Wow, incredible blog layout! How long have you been blogging for? you make blogging look easy. The overall look of your web site is wonderful, as well as the content!

    • Simo says:

      any video tutorial of soomnee programming is going to look like the code you see in a book being typed into a blank window. you say you are visual which is fine, but a book *is* visual. coding is typing abstract text into a piece of software, and a book really is the best place to learn this. maybe there are video tutorials of coding out there but i doubt it.

  11. Spot on with this write-up, I really assume this web site wants rather more consideration. I’ll in all probability be once more to read far more, thanks for that info.

  12. Meghan says:

    Your home is valueble for me. Thanks!…

  13. The subsequent time I learn a weblog, I hope that it doesnt disappoint me as much as this one. I imply, I do know it was my option to read, however I truly thought youd have something interesting to say. All I hear is a bunch of whining about one thing that you could possibly fix when you werent too busy looking for attention.

  14. phen375 gnc says:

    Excellent site you’ve got here.. It’s difficult to find excellent writing like yours these days. I honestly appreciate people like you! Take care!!

  15. Reached your blog post through Digg. You already know I am signing up to your rss feed.

  16. Writing WordPress Guides For The Advanced Beginner : dot Key Plugins I was suggested this blog by my cousin. I am not sure whether this post is written by him as nobody else know such detailed about my difficulty. You are wonderful! Thanks! your article about Writing WordPress Guides For The Advanced Beginner : dot Key PluginsBest Regards Justin

  17. “Hello my friend! I wish to say that this article is awesome, nice written and come with approximately all significant infos. I would like to see more posts like this .”

  18. Nice post at Writing WordPress Guides For The Advanced Beginner : dot Key Plugins. I was checking continuously this blog and I am impressed! Extremely useful info particularly the last part :) I care for such info a lot. I was seeking this particular information for a long time. Thank you and best of luck.

  19. capsiplex says:

    This is really interesting, You are a very skilled blogger. I have joined your feed and look forward to seeking more of your wonderful post. Also, I’ve shared your web site in my social networks!

  20. fkawau says:

    This is the rectify Writing WordPress Guides For The Advanced Beginner : dot Key Plugins journal for anyone who wants to seek out out active this issue. You attention so such its nearly wearing to argue with you (not that I really would want…HaHa). You definitely put a new whirl on a theme thats been graphic active for age. Squeamish meaninglessness, just uppercase!

  21. Cherilyn says:

    Now we know who the senbsile one is here. Great post!