Google+
4elements web design & consultancy

Shineyrock

web design & consultancy
Shineyrock web design & consultancy

Shineyrock

  1. web design and consultancy

blog

  1. Home
  2. blog
  3. read
  4. Writing Documentation for Your WordPress Theme Framework
  • dislike -11 22

    Writing Documentation for Your WordPress Theme Framework

    1. January 2015
    2. Daily
    3. read 839
    4. response 1

    So, you now have a WordPress theme framework. Congratulations! The hard work you've put into developing it will pay off in the long run and make your development process smother, more streamlined and more efficient.

    But you need to do one last thing before you're finished, and that's to document your framework. At the very least you'll need to ensure good commenting is used throughout your code, but it's also helpful to write some other documentation so you can keep track of the files, functions and filters that make up your framework's API.

    The options I'll cover are:

    • Commenting
    • Creating a readme file
    • Using automated documentation tools
    • Creating a wiki
    • Creating a website
    • Creating tutorials or recording videos

    Note that while I'll be mentioning a few documentation tools, this tutorial doesn't serve as a recommendation as I haven't used them for my own framework, so you'll need to make your own judgement as to their suitability.

    Writing Quality Comments

    Comments are particularly important when other developers will be working with your code (for example if you're part of a team or if you'll be releasing your framework). But they're also invaluable if you're working on your own, as it's very easy to forget exactly what a piece of code does when you come to edit it a year or more down the line.

    Imagine you've used your framework to build a client site. Two years from now, the site develops a problem at 5:30 on a Friday afternoon. Good comments can make the difference between fixing the problems quickly and being home for the weekend, versus slogging through hundreds of lines of code and missing your Friday night out.

    Here are some tips for good comments:

    • Use comments at the beginning of your file to explain what the file does. For example, in template files include a note about what data it displays and any customizations you’ve made to the loop or other parts of the file; and in plugin files add a note regarding its functionality. For example. the comment below tells users the name of the template file, what it does, the theme it is part of (@package), and which version of the theme it has been in place since (@since). You should use a similar system for plugin files.
    /**
 * Template Name:    sidebar-products.php
 *
 * The include file used for the sidebar on pages using the single-product.php template. Displays a gallery of product images (omitting the featured image which is displayed in the content).
 *
 * @package wpptl-theme-framework
 * @since version 1.0
 */
    • Use comments to demarcate the sections of your code, not only in stylesheets but also in your theme template files and functions file.
    • Comment anything that is nonstandard.
    • Comment anything that took you a while to work out — use detailed comments so when you come back to it, you don’t have to think it through again.
    • Comment anything that you know someone else will be working on — for example, if your theme files contain scripts that you’ll be asking another developer to perfect, add comments explaining where they apply in the site.
    • Use wording in your comments that you can find using a search later — so don’t abbreviate, and use terms others would understand.
    • Whenever you comment out some code, add a comment to yourself containing the reason. That way, if you forget to remove the code after you’ve finished, or want to add it back in the future, you’ll know what’s going on.
    • When in doubt, add a comment!

    Creating a Readme File

    A readme.txt file is the next level up after commenting. It's a single file which you include in your theme, containing information about the theme.

    The code bundle to accompany this series includes a simple readme.txt file:

    Creating your own WordPress theme framework

This theme supports the 6th part of this series for wptutsplus.

The theme includes the following template files:
archive.php
index.php
page.php - for static pages
page-full-width.php
archive.php - for archive pages
header.php
sidebar.php
footer.php
loop.php
loop-single.php
loop-page.php
functions.php

The theme supports featured images, menus and widgets and uses them as follows:

Featured images:
These are displayed in the archive and index templates if they are present, using the medium size.

Menus:
The default menu is in header.php, and uses the Menus admin

Styling
The theme uses Object Oriented CSS (OOCSS). The following clases are for layout and you can use them in your pages and posts.
They are responsive, so will resize on smaller screens (for example the .half class is full width on phones)
.full-width
.three-quarters
.two-thirds
.half
.third
.quarter

Hooks
There are 7 action hooks:
Above the header
Inside the header
Before the content
After the content
In the sidebar
In the footer
After the footer

There are 3 filter hooks:
1 in the header
2 in the footer


Widget Areas
There are six widget areas, all added via the widgets.php file:
- one in the header
- one in the sidebar
- four in the footer

    If you want to make your readme file more user-friendly, you might want to consider creating a readme.html file instead which will open in a user's browser. You can use CSS to brand your readme file and make it easier to read.

    If you want to release your theme to the public via the WordPress theme repository, you will be expected to provide a readme.txt file as a minimum form of documentation. I'll cover this in more detail in the final tutorial in this series, on releasing your theme framework.

    Using Automated Documentation Tools

    If you plan to continue developing your framework and don't want to spend a lot of time manually writing documentation for every new feature, an automated documentation tool may be the answer.

    Most of these involve using specific tags or syntax to enable the system to identify where to generate documentation. Examples include:

    If you are going to use one of these tools, it's worth spending some time identifying the best one for you before you start, as you won't be able to transfer your documentation from one to another. 

    But once you've come to grips with the system and got it set up, an automated tool like these can save you a lot of time and can avoid gaps in your documentation down the line, as you'll be so busy writing code you don't have time to update your docs.

    Creating a Wiki or Website

    This option will be more work and is only worth doing if you see your framework growing over time and gaining a significant user base. All of the major theme frameworks have their own websites with documentation, which is either freely accessible or available only to members.

    The website to support your framework could form part of your monetization strategy - the hybrid theme framework, for example, is free, but the documentation and support on its accompanying website are only available to paying subscribers.

    Alternatively if you're releasing your framework as a premium product, you could require subscribers to login to the docs, or you could choose to make your documentation public in the hope that it will encourage more people to buy.

    If your framework is completely free, you might choose to create a free website with documentation, as is the case with the Wonderflux framework:

    Alternatively, you might decide to create a wiki, which has the advantage of letting your users contribute to the docs. This will take more time to set up than a website in most cases, but could be a valuable tool for the community using your framework. You can create a wiki using a plugin for your framework's WordPress site.

    Creating Tutorials or Recording Videos

    Tutorials can help new users, in particular those who can't write code, get to grips with your framework quicker than standard documentation. Videos take this a step further, providing an easy to use visual guide and a great marketing tool.

    The Genesis framework has a range of tutorials for users which are only available to paid subscribers:

    My own Edupress framework has a number of tutorial videos which I created to help users with a varying degree of computer experience and little experience of using WordPress:

    These are displayed on the public website and also in users' dashboards so they can easily access them while working with the framework. If you create documentation, tutorials or videos for your framework, you might include a screen in the dashboard with details of the your docs.

    However, creating tutorials or videos is very time consuming and needs a lot of work to get right: badly written tutorials or poorly produced videos will reflect badly on your framework and may do you more harm than a simpler form of documentation. 

    Summary

    Whoever's going to be using your theme framework, some sort of documentation is essential. Whether you're just developing the framework for you and your team, or releasing it for wider use, you'll need to record information on the file structure and the API.

    The options I've discussed above range from the simple comments to the more complex videos, with everything in between. What you decide to do will depend on the needs of your users, and may well change over time as you gain a larger user base.

    Photo

    martijn broeders

    founder/ strategic creative at shineyrock web design & consultancy
    e-mail: .(JavaScript must be enabled to view this email address)
    phone: 434 210 0245
    Add a comment...
    4elements
    Comments
  • 1
    silhouette
    troymolnar
    January 24, 2015 at

    I just couldn't depart your website before suggesting that I actually enjoyed the standard info an individual provide for your guests? Is going to be again continuously to check up on new posts

    4elements
    Comments

By - category

By - date

Copyright © 1999 - 2026 Shineyrock web design and consultancy, All Rights Reserved / Terms of Conditions / Sitemap: XML, HTML, Images, Mobile, News