Helpful Tips for Documenting WordPress Themes

When you have a question about a WordPress theme, where do you look for more information? Theme developers make use of a myriad of documentation methods, from bundling docs to linking to external resources. If you’ve already created a theme and taken the time to document it, then your next challenge is to make its documentation easy to discover.

When documentation isn’t readily available, users will take to the forums to get answers to common questions that could have easily been outlined in a few quick notes. This increases your support burden and causes delays for users who are trying to customize your theme. Let’s examine a few ways to make theme documentation easier to find.

WordPress.org Theme Documentation Recommendations

Themes hosted on WordPress.org tend to enjoy a large audience and have guidelines to protect their large user base. I spoke with Chip Bennett, who heads up the WordPress.org Theme Review team, to find out how WordPress.org recommends documenting themes. These recommendations are helpful even if you’re documenting a commercial theme or one not hosted on WordPress.org.

Where is the best place for a WordPress theme author to place documentation so that their users can easily find it?

Bennett’s advice, as quoted below, includes a combination of four different methods:

1. readme.txt
   The Theme Review Team recommends placing all theme documentation in a readme file, ideally in the format of the Plugin-standard readme.txt markdown.
2. Admin Contextual Help Tab
   Another good documentation location that is woefully underused is the WP Admin contextual help tab. Themes that incorporate a settings page should definitely consider using the fairly rich Contextual Help API.
3. Forum Sticky Post
   For any immediate support issues, a support forum sticky is a great idea.
4. Theme URI for External Docs
   And finally, themes can declare a Theme URI, which is intended to be an information/documentation resource for the theme. If any of the built-in documentation methods are too limiting, theme developers are welcome and encouraged to use ThemeURI (which can be a domain, subdomain, or landing page specific to the Theme, or even a GitHub repo/site for the Theme, with documentation).

Theme Documentation Best Practices and Examples

Now that we’ve covered where to place theme documentation, what should be included? Bennett recommends that you start with licensing attribution and use documentation to explain setup and anything out of the ordinary.

“Some best practices for theme documentation include explicitly stating the copyright/license attribute for all resources bundled with the theme, explaining any unusual/non-standard setup instructions for the theme, and explaining any non-core-UI theme functionality,” he said. “For inline documentation, I strongly encourage developers to follow the phpDoc standard, which improves readability, and allows for automation of generation of theme documentation.”

Best practices for theme documentation are not unduly strict, in that you can utilize virtually any route you choose, extending beyond the four methods recommended by the Theme Review Team.

“Almost any method of documentation is encouraged,” Bennett said. “Theme developers can certainly bundle help docs with their themes. Some use plain-text readme.txt or readme.md files; others use HTML files, rich-text documents, or even PDFs,” he said.

“The only downside is that there is no standard/easy way for the end user to find/use those documents,” Bennett cautioned. “Again, the Contextual Help API could be useful (it can be used to display rich text/HTML, or to link to a Theme-bundled PDF, for example), as well as the Theme URI.”

Bennett also notes that the way you choose to implement theme features will directly affect how much documentation you need to produce. “[pullquote]Another important best practice is always to incorporate features using the WordPress core implementation, so that fewer such features even need to be documented[/pullquote],” he said.

“For example, when implementing custom header images or custom backgrounds, using the core implementation provides a standard, intuitive UI for the end user. Similarly, when implementing a custom static front page, or a custom blog posts template, properly implementing the Template Hierarchy will avoid the need to provide instructions for a non-standard implementation of those features.”

Bennett offered a few examples of themes that have solid easy-to-find documentation. He developed his Oenology theme with excellent documentation as an intentional goal. The Oenology options page makes use of the contextual help tab to provide additional information on settings, FAQ, a changelog, support, and licensing.

Theme developers can check out Oenology theme files to see how Bennett incorporates documentation into the theme itself. He also recommends Underscores as a well-documented theme.

More Documentation Options Coming to WordPress.org

WordPress.org plugin authors have the option of adding additional documentation to the FAQ and Installation tabs. When I spoke with Bennett, he explained that theme authors do not yet have this capability.

“The Theme Directory is much more limited because, while the Theme and Plugin directories look essentially the same on the front end, they are two entirely different beasts under the hood,” he said. “The infrastructures are different. That said, there will be some changes in the (nearish?) future, that will allow the Theme directory to emulate the same (or similar) functionality, based on a standard readme file format.”

The Theme Review Team will be discussing how improvements can be implemented, but it’s not yet clear what those changes will look like. In the meantime, theme authors can make use of the solid documentation recommendations Bennett outlined.

Good documentation requires a little bit of strategy to find the best way to connect with your users when they need help. Chip Bennett’s tips are useful to all WordPress theme authors, whether you’re creating a custom theme for a client, selling a commercial theme, or supporting a free theme on WordPress.org. A combination of approaches via the readme.txt, inline documentation, contextual help and external docs at the Theme URI will cover all your bases.

Take the time to create high quality documentation and you’ll find that the burden of support will decrease. As a WordPress.org theme author, I’d prefer to spend my time making updates and developing new features and themes. Using WordPress core implementation for features and providing good docs is the best way to free up your time to do more of the fun stuff – creating beautiful themes that users will love.