Using WordPress as an API Documentation Blog
Well written, easy to understand documentation for programming languages, software, APIs and other computer applications is a must. After all, what good is an application, programming language or API if people cannot figure out how to use it? As a web developer, I recently had a project where I was commissioned to build a sports and weather statistics API where users can connect to the API and retrieve stats on sports and/or weather. I soon found out that creating the API documentation was almost as big of a challenge as creating the API itself. What I initially thought was a minor task turned out to be quite complex. However, creating the documentation platform would have been much simpler and less time consuming if I had known what to do from the start. That is why I created this advanced WordPress tutorial on how to use WordPress to create a documentation blog for software applications, APIs or anything else that needs hierarchy based documentation. The same method could also be used for e-books, site maps, other websites and online tutorials as well. The list of possible uses goes on and on.
What is a Hierarchical Table of Contents?
A hierarchical Table of Contents is a table of contents (TOC) that has a series of main categories and sub categories rather than a simple list of pages or sections. For my client’s project requirements, I needed to make a TOC with three main categories with each having several sub categories. The individual document posts would be listed under the subcategory that best describes them. You may need a different number of categories and subcategories, but no matter the number, the basic instructions will be similar.
To use this tutorial for making a documentation blog for your software, programming language or other product, you should know how to code in PHP, CSS and HTML. You also need to understand the very basics of how to install both WordPress themes and plug-ins. Some general knowledge of WordPress inner functions and the WordPress loop is also recommended.
Issues to Overcome
The main issue I had to overcome when setting up WordPress to use as a documentation platform was getting a hierarchical table of contents to fit my needs. An easy to understand table of contents is very important to any online documentation because it serves as a quick and easy way to find the specific document the user is looking for without having to comb through the entire documentation site.
The problem with WordPress’ default behavior is that it does not allow multiple categories and sub categories and the default TOC is plain and ordinary looking. I will demonstrate and explain how to overcome this issue further on in this tutorial.
Another feature I was searching for was a way to search the documentation quickly so users can enter what they need in a search box and have the site quickly pull up matching topics in the documentation. This wasn’t a huge challenge, but it could be if you start out on the wrong foot.
Setting up WordPress for use as a Documentation Site
Normally I do not recommend using plug-ins or themes in the advanced WordPress tutorials I write. Instead, I usually favor writing them from scratch, but I am doing something different in this tutorial because I want to save time and keep development costs to a minimum. Developing a theme and/or plug-in from scratch to make a documentation site would not be economical in regards to both time and money. Most people are not going to want to spend a whole lot of extra cash on the documentation for their software after they already spent a small fortune developing the software, application or API. That is why we are using this more economical method of developing a WordPress documentation blog.
Options for WordPress Documentation Blog
Before we found what we figured was the best working solution, we tested many plug-ins and themes that all claimed to be perfect for online documentation purposes, but none were even close to perfect in the end. We are ultimately going to tweak an existing theme and plug-in to accomplish a sleek easy-to-use documentation blog for our specific needs.
One of the plug-ins we tested first was EasyDocs. EasyDocs is a WordPress plug-in specifically made for software documentation. The problem was that it only allowed for one main category at a time. It would not work for our needs because we needed to have three main categories and the option to add more as needed.
There is one possible way EasyDocs could work. The only way it would work without major modifications would be to install a separate WordPress installation for each major category. Yes, that would work, but it would be bulky and more difficult to edit because you would have to login to a separate WordPress installation each time you wanted to update a different category’s documentation. It would involve a lot of duplicate files and take up an unnecessarily large amount of disk space as well. Using separate WordPress installations with the EasyDocs plug-in is not the most practical solution by far. We quickly dismissed that option once we found the proper plug-in for our needs described below and figured out how to make it work with the simple default twentyeleven theme for WordPress.
From digging a little deeper we found a plug-in that was closer to what we needed. It was called “Table of Contents Creator” or TOCC for short. TOCC does come with a hierarchical TOC like we need, but it was not customizable enough in the end to work as-is, so we installed it and tweaked it to fit our needs since it was the closest thing we could find to what we needed without having to purchase an expensive plug-in and/or theme.
The main problem with the TOCC plug-in was that it did not lay out the table of contents exactly how we wanted it to. It is fairly customizable in the settings, but it takes a bit of time to completely understand the settings. We will walk you through the important setting changes below.
Tweaking the TOCC Plug-in
Here is how we make the TOCC plug-in work for our WordPress documentation blog.
Setting up Categories and Subcategories for your TOC
The first think you are going to have to do to make the TOC work is set up a table of contents infrastructure for it to follow. We do this by setting up WordPress post categories. Since by default, categories only work with posts and not pages, this means that we will have to use posts for our documentation pages, which is fine for our needs. However if you have to use pages instead of posts for any reason, you can with a little different methodology than what we use here, but that is outside the scope of this tutorial. Here is how I set up the categories for my TOC. Remember, I said I needed three main categories. They are going to be:
>NFL API Queries
>MLB API Queries
Each will have one or more subcategories. For example, the subcategories for the MLB API queries are going to be:
>MLB Team API Queries
>MLB Player API Queries
Each of the three main categories will have its own subcategories The actual documentation posts that explain the MLB query types for our API are going be listed under the above two MLB subcategories. We won’t need any subcategories for the main category named “Weather Queries” because there are none and we can simply list the query instruction posts under the main category for this one.
One issue I encountered with the TOCC plug-in was that it won’t allow a category to show unless it has at least one post even if it has subcategories with posts. You could have your categories all set up and have several posts under the subcategories, but they would not show up in the table of contents because there was no post assigned to the main category! To solve this issue I had to put at least one post under each of the main categories. I found that this was a great place to put either an introduction, instructions or both to explain how to use the API documentation. Once you have a post assigned to the main category, all the subcategories and posts under them will show in the TOC. This is important to note because if you don’t realize this, you’ll end up like me scratching your head for a half hour.
Setting up WordPress Categories
Now that we have our basic infrastructure mapped out, we can go to the WordPress dashboard and add the necessary categories to make it all work. If you have not planned out your categories like we have above, sketch them out on a piece of paper or using your word processor before you continue so you know exactly what categories and subcategories are needed for your site. If you don’t know all of the ones you will need at the start of the project, don’t worry, you can always add more later. Just map out the ones you know you will need for now. Here is how to do it in WordPress from the admin dashboard:
In the dashboard’s left main navigation menu, under posts, click on “Categories” to open the category dialog.
In the left column of the category dialog is the “Add New Category” section. Enter the first main category name first. Then enter a URL friendly version of the name in the “slug” field. In the parent field, select “none” only for main categories. For subcategories, select the name of the parent instead. In the description field, enter a brief description of what the category covers. The description you enter will show up directly under the category name in the table of contents. Be careful what you put there since it will be seen by everyone. Finally press the “Add New Category” button at the bottom and it will save your new category and you can go and enter the next one.
Repeat step two until you have all the categories and subcategories you think you will need for your online documentation site or blog.
Start Entering Document Posts
Now it is time to start manually entering your site content which will be the documentation for your software, API or other product. The content of course will consist of documentation posts, each of which should contain instructions regarding a single subcategory or category in the table of contents. Be sure to use only posts to write your documentation because that is how we set up our table of content’s categories. Before any of the posts will show you have to make the main category visible by entering at least one post with that category selected. In my case, since I had no formal documentation requirements for the main categories and since you have to enter a post for the main category, I entered a post named “MLB API Introduction” under the main “MLB API Queries” category.
The next post I entered had instructions on how to make queries to get MLB team stats. I entered it under the subcategory of “MLB Team Queries”. I also entered documents on how to make player queries under the subcategory named “MLB Player Queries”.
Next I entered an introduction for the NFL API under the main NFL category just to make it visible for now. Okay, My TOC is not yet complete, but after finishing all that, my table of contents it complete enough for demonstration purposes and looked like this:
Here is what it looks like with the sub categories all closed (you can choose to have them either closed or open by default in the plug-in settings menu):
Here is what it looks like with everything fully expanded:
You can see from the above images how we made our hierarchical table of contents for our documentation blog. I did make a couple changes to the layout in the CSS and images to make it look that way, but the default look isn’t much difference. I will quickly explain how you can customize the look as I have in the above image.
Customizing the Table of Contents Style
The first thing I did to customize the look was to use the red triangles as bullets because the default image used by the Table of Contents Creator plug-in was a quote symbol that just doesn’t fit for a documentation site. Here is how to change out that image:
First we changed the post bullet images. The image needs to be changed from the plug-in’s directory, not the theme’s directory like you may have suspected. The image you need to find and replace is in the directory …/your-WordPress-dir/wp-content/plugins/table-of-contents-creator/icons/professional/img_blog_post.gif.
Simply delete the image and replace it with one of your choosing. Be sure to give the image the same name and size and it will work perfect. If you want to change the folder icon in the TOC, it is in the same folder, but the name is “img_blog_cat”.
If for some reason you have to use images of a different size, you will have to edit the style sheet for the plug-in to make it work as well. The style sheet is located in the …/your-WordPress-dir/wp-content/plugins/table-of-contents-creator/ directory and the file is called tocc.css. The class to look for the help icon we used was “tocc_help_icon”. That was the only one I changed that needed the style altered because I used a larger image. Some may need style adjustments and others may not, so if it doesn’t look right, find the style and alter it as needed for your images.
Altering the TOC header
After you are done changing the images, the next thing I did was edited the h1 heading on top of the TOC where it says “Table of Contents. It was small by default and my client wanted his larger. You can do what ever you like to yours. Here is how you can edit the TOC header:
Go to the WPS dashboard and click the “Settings” menu and select “Table of Contents Creator”.
From the settings dialog you can find settings for the h1 tag to change the TOC header. Here you can change the text to whatever you want and add inline style to the h1 tag if you wish to change color, size etc…
Changing the Color of the Links in the TOC
After I edited the h1 tag I edited the link color for the TOC. It was blue by default and my client wanted his orange. Here is how I did it:
From the dashboard again, select “Theme options” under the “Appearance” menu
In the dialog that appears, the second option there will be “link color” edit it as you desire and that is that. However, if you don’t want the links on the rest of the site to change, you don’t want to use this method. An alternate way to do it in that case would be to find the code in the plug-in file and add a class to it and then add the style to the style sheet. There is a style sheet for the plug-in in its main director called tocc.css.
Other Possible Changes to the TOC Look and Functionality
There are all sorts of things you can change in your own document site from the TOCC settings menu. For example, you can change the text that appears under the main heading. You can see in the above images, I changed my sub heading to “API Docs” from this settings menu. You can also change the page title, the options menu border, the help text and a lot more. Go over all of the settings and customize the look and feel of your table of contents as you see fit.
There you have it! With the methods used in this tutorial you should be able to create your very own custom online documentation site or blog for just about any purpose you can think of that needs documented. All you need is WordPress, the Table of Contents Creator plug-in and the default twentyeleven WordPress theme. Then tweak to order and you are ready to go! Good luck developing your documentation blog and be sure to follow WordPress standard practices whenever possible.