Documentation Contents

BackgroundDownload at WordPress.org

I work on the openxdata.org websites including the documentation site doc.openxdata.org which are powered by WordPress. As we started to add new versions of the software there were some features that changed and some that hadn’t. I didn’t want to have to duplicate effort or content in order to make new manuals for newer versions.

So I made this plugin that lets my tag each of my documentation posts which the versions of your software that it applies too. Then I can easily generate a table of contents for each separate version of our software that pulls together all of my relevant posts.

Usage

Shortcode

In a page or post where you would like to display a table of contents enter the following shortcode.

[documentation-contents tag=”v1.16″ parentcat=”server”]

The above shortcode is used to display the page here. The tag specifies the tag that you have used to mark the version of your software. The parentcat is optional. If you don’t specify it, the software will first look for a default parent category set in your Options and will finally just default to all.

Mark versions of your software using  Tags

Use the WordPress tag feature to tag your post with the different version of software that it applies too. You can tag the same post with multiple versions so that you don’t have to duplicate content.

Organize your documentation into chapters using Catagories

By marking your post as being in a category, that is the chapter that it will end up in. Your Table of Contents will use Category names as chapter headings.

WordPress allows you to create categories with sub-categories. You can use this feature to host documentation for different things in the same place. For example, the below snapshot shows the categories from doc.openxdata.org. You then mark the parent (top-level) category in the shortcode e.g.

  • [documentation-contents tag=”v1.16″ parentcat=”server”]
  • [documentation-contents tag=”v1.16″ parentcat=”mobile”]

You can set a default parent category in Options

Use a custom field for fine-grained control over the order in which lessons appear.

In the absence of a custom field, the posts will just be displayed in alphabetical order.

However, I don’t find that its a good idea to use numbers in my post title to specify order. Because a lesson can be used over and over again for multiple versions then you’re not always guaranteed that the first number you give it is going to be the right one.

So, in the options (see below) you can specify a custom field. Once you start with custom fields, you can’t go back. All posts that you want to show up in your documentation must have this custom field.

I use “lesson_order” as my custom field and as I’m starting out I use 10, 20, 30, 40 etc. That means that if I add an extra lesson later, I can make it 31 or 32 and I won’t have to change anything else and it’ll work just fine.

Options

Under the administration dashboard, Settings, you’ll find a page Documentation Contents

Contents Header is used as a custom prefix, so if you don’t want it to say “Table of Contents” for xxx it can say “Documentation” for (like in the above picture) or anything else you want.

Default Category is used to specify a default parent category, to save you typing out parentcat=”xxx” in each shortcode that you use.

Specify order with Custom Field. If this is not set, then posts will be listed in alphabetical order. If you do set it, then you will need to mark all your posts with this custom field in order for them to be displayed.