Using WordPress for Product Knowledge Base

May 31, 2013 at customer support, technical communication, technology

Technical documentation has traditionally been developed in HATs or XML editors. It is only in recent years that the content management systems have caught the attention of documentation managers and authors as a potential platform for technical documentation. One of the most commonly used open source CMS is WordPress, and it has really evolved from merely a blogging tool to a product development CMS.

I talked on WordPress for Technical Documentation at TCWorld India Conference 2013, earlier this year in Bangalore. The slide deck is available at slideshare.

In this post, I share my experience of using WordPress to develop the knowledge base for a B2B marketplace.

Using WordPress–A News to Me

When the client approached me, one of the first requirements was to use WordPress. It was a news to me because I had never used it for product documentation. In additional to using HATs and XML authoring software, I have developed support centers using helpiq (now ProProfs) and in core HTML/JavaScript, similar to that of getharvest. However initially, I was not too sure of taking up the project because I do not know PHP and it meant I had to seek assistance from a WordPress programmer.

I spent a few days to understand the product workflow, and I drafted a high-level structure of knowledgebase. My first few discussions with the client helped me formulate the requirements document. It included:

  • Skype support center was the reference
  • Different content types including those for videos
  • User generated content, somewhat similar to how it works on Skype community support
  • Global content such as Most Viewed Topics, Top Rated Questions, Top Rated Videos
  • A custom design

My technology associate, Shena is a Drupal expert and she told me that Drupal would be an ideal platform to develop a product knowledge of this scale. A few recent posts by Tom Johnson strengthened my belief in what Shena suggested me that time. So I was convinced that a CMS (WordPress or Drupal) gives us a lot of flexibility to customize our online manuals. I encapsulated it in one of the slides, as below.

Vinish Garg WordPress Product Knowledge Base

The Specific Requirements

Since Skype was the reference (although not for UX/UI), we documented the key requirements as below.

  • Categories and sub-categories for topics
  • Content blurbs for each category and sub-category with pagination options
  • Custom block in sidebar for featured/specific/popular categories or sub-categories
  • Custom block in sidebar to connect with user generated content and community pages
  • Custom block in sidebar for contact support options
  • Community pages with advanced options to flag, share, like, see author profile
  • Related topics
  • Related topics from community pages
  • Integrate the knowledge base users database with the product users database

See a couple of slides for how we can setup WordPress for these requirements.

Vinish Garg WordPress Product Knowledge Base

Vinish Garg WordPress Product Knowledge Base

Summary of Knowledge Base Requirements

The requirements from Skype reference along with all additional comments by client helped me prepare the requirements cart, which looked something as below.

Vinish Garg WordPress Product Knowledge Base

Implementation

We planned the architecture and it was challenging and the fun at the same time. There were very few restrictions on what I could not try or do (we are so used to feel restricted when we use a HAT). A few important features that we could successfully implement are listed below.

Ratings

The users could rate a topic, and rate a video separately. The interesting part was that we needed to fetch ‘top rated questions’ and ‘top rated videos’ separately, because all these were not fetched from same content type. This was challenging, and this is how we managed the rating system.

Vinish Garg WordPress Product Knowledge Base

Videos

We needed a video gallery where users could see a list of videos and click on any thumbnail to see a video tutorial.

Flexible TOC

Managing TOC and then the ability to restructure the TOC is always a critical requirement. We used ‘My Category Order’ plugin to implemented it.

Intuitive Search Experience

WordPress has its default search system. We used Ajax to give an enhanced user experience for search, as below.

Vinish Garg WordPress Product Knowledge Base

This is merely an extension of what WordPress offers as default search. However, Search and Findability have a lot of scope of planning and implementation as Tom has discussed in his few posts, for example here. I am excited to know that Tom advocates using CMS (Drupal) now since it aligns with my thought process as well.

Versions

WordPress offers a default basic level version system. However there are plugins available that you can install and customize for specific requirements including roles and privileges.

Summary of Custom Requirements

Here is a quick summary of what all WordPress offered to us in this knowledge base development.

    • Custom theme
    • Analytics (Google Analytics or even advanced analytics such as Woopra)
    • SEO
    • Collaborative authoring
    • Role based access
  • Advanced WYSIWYG (custom classes integration)
  • Immediate control for community participation
  • Version control

A few advanced features that we planned are:

  • Export to PDF (Standard as well as conditional)
  • Archive Posts
  • Variables (Template parts)
  • Custom Taxonomy for advanced user experience

Conclusion

When I say that WordPress is a good enough tool for product documentation, it does not mean that other tools may not be good enough. WordPress has its own limitations such as for:

  • XML support and DITA
  • Accurate localization
  • Support to import external documentation project files
  • Security concerns

However, every tool has its limitations. My objective is not to advocate WordPress as the best authoring tool, rather it is also part of the plate.