Why theme documentation matters

Creating WordPress themes can be fun. Sharing them with everybody is even better. What happens when those users then ask you how to do something? Often times what is the simplest task to you may seem like a trip to Mordor for others. You don’t always know the person’s knowledge base when you share your theme. They could be a developer that began using BASIC when it was first introduced, or a person who has just picked up a book on how to build a website using WordPress.

What’s cool is we can meet both those worlds in the middle. One way is by using code comments. Code comments can make it easier for not only yourself but others to know what exactly the code is doing. A good example of this is the comment block below, taken from the wp_get_theme function:

/**
 * Gets a WP_Theme object for a theme.
 *
 * @since 3.4.0
 *
 * @global array $wp_theme_directories
 *
 * @param string $stylesheet Directory name for the theme. Optional. Defaults to current theme.
 * @param string $theme_root Absolute path of the theme root to look in. Optional. If not specified, get_raw_theme_root()
 * 	                         is used to calculate the theme root for the $stylesheet provided (or current theme).
 * @return WP_Theme Theme object. Be sure to check the object's exists() method if you need to confirm the theme's existence.
 */

Yes, it can look like a lot of information but not all your code has to be as robust as that. You can use simple documentation and still do just the same. While that does go for some developers, we cannot forget those that just want to use the theme and are possibly afraid of code, or don’t know how to code. Great! This is where other forms of documentation come in handy.

Types

There are other forms of documentation that you can use to your advantage. A few I like are:

  • Videos
  • Images
  • Readme file

Please note, images and videos may not always be view-able by all so you may have to take that into consideration on your path to documentation bliss. Now, let us explore those a little more.

Videos

I love me a good video. A video tutorial, that is. Now, your theme does not have to have a step by step video on how to setup every single option, or possibility your theme offers but you do want to have some of the basic, and perhaps most common things. A few examples are installing the theme, accessing your theme options, showing how to setup possible social links, or even using page templates. You don’t have to have audio but it does help. There are several programs out there that allow you to capture video and create video screen casts.

Images

Yes! Images can make a huge difference for many. Even better when they move. I am talking about gif images. They can be a great way to showcase a few steps without having to create a two minute video to show how to access extra options. If you have an image editing program it can be used to highlight what you want in order to emphasize parts of the image.

Readme File

The basic and standard file you need to include. Okay, that’s just me saying it but I’m sure there are more people who would agree with that statement. This is the part that really irks me because you can include some basic steps that can go a long way. A great example is setting up social link profiles. There are several ways of creating those and not all themes follow a standard. It is nice to know where to look and how to use it.

== Setting up social links ==
1. From Dashboard go to Appearance
2. Click Customize
3. Go down to Social section
4. Type username or ID ( depending on network )

Looks fairly simple, right? It can be for some but there may be others that may still get confused. Okay, we covered a simple setup but what happens when a user gets what they feel is an unexpected result?

What do I mean by this?

Let’s say the theme has a menu location at the bottom and you only want it to display one level of menu items. They may open a support request, thread, ticket, whatchumacallit, or what ever system of support you are using and ask why it isn’t showing all the menu items. This is where your theme’s documentation can come in super handy and essential. If it is a design choice then it should be stated in the documentation. A good way would be something like:

=== Limitations ==
* Featured images should be minimum 600 pixels wide and 400 pixels tall for best results
* The `footer-nav` menu location, by design, only displays one level of menu items
* The `ad-loc-1` widget area is only used in the page template `fullwidth-ads`
* If pages do not have a featured image set, the chosen header image will be used

Yes, even what sounds -or seems- strange is super helpful to the user of your theme. Knowing what the best size for an image is useful, just like knowing the right size of tire for your car or bicycle.

So please, please make sure you are documenting for not only yourself but for your users as well.

By Jose

Born in El Salvador. Loves to read, write, draw, paint, build, test, typography, hike, photography, art, design, sewing, and many other things.