How To Build A Help Authoring Tool Using WordPress

Last updated on April 13, 2024

Written By: author image

Chris Hadley

A good technical writer is never far from their trusted help authoring tool (HAT).

The workhorse of the technical writing trade – a help authoring tool, takes the strain and transforms the art of ‘making complex things plain’…well, a cinch.

HATs are productivity maximisers for technical writers. 10x technical writers have this side of their game firmly set.

With so many phases of iterative rounds of shaping and editing copy to have it land as a perfect fit for purpose…

…you really need a HAT that will work alongside you and help you focus all your efforts into formulating the best literary product.

The concept of a HAT is not new.

They’ve been around.

And some might say, if they were a family photo they might have become slightly dog-eared, sepia’d and even faded in relevance.

For example, in many cases, possessing a WYSIWYG editor is considered a premium feature.

But thinking more laterally, is there a case for applying the versatility and multifaceted transferable benefits of a content management system (CMS) to catapult HATs into the 21st century?

We’d argue, in the case of WordPress CMS – the world’s leading web building platform and most popular CMS software by a country mile…

…the answer is: YES.

But don’t just take our word for it, why not take the next few minutes to delve a little deeper into why WordPress CMS is the next best thing to happen for technical writers since ~~sliced bread~~ espresso coffee.

Here it is, the HeroThemes guide to building a help authoring tool using WordPress.

The Typical Demands of Today’s Technical Writer

Technical writing today spans many specialist subjects.

Governmental public policy
I.T. computing
Financial investing
Real estate

…the list goes on.

But common throughout are the rigorous demands of being translators of complexity to the technical world are the day-to-day tasks.

According to Khidr Suleman, Technical Writer, Service Design and Assurance at UK Government Digital Service – the following are his regular daily duties:

participating in user research
creating content strategies
presenting plans to senior stakeholders
designing and prototyping user journeys
discussing, editing and (of course) writing content

Quite diverse.

Yet, last but not least on that list was (of course) doing what they really do.

But writing (and especially technical writing) is a process rather than an activity.

A relay race of duties that collectively lead to delivery of documentation.

In a nutshell, technical writing can be described as being the process of “…capturing, organising and maintenance of knowledge about rapidly changing software systems” – Atom Bank

And as such, a common feature of a day in the life of a technical writer is handling repositories and knowledge bases.

Recording citations or snippets of expert commentary, for example. As well as, retrieving golden nuggets in the form of fact or data to validate arguments.

In short, ease of data storage, search and location or discovery – aside from writing – are also an important allied functions of a help authoring tool.

What is a Help Authoring Tool in 2022?

If the majority of page 1 Google definitions for help authoring tool are to be believed, an accurate description should include:

Making
Managing
Publishing

…documents.

Most claim a better identity would be ‘content management system’.

Granted that this term tends to be included within articles written by CMS vendors (and in that regard, this article wouldn’t be any different), but if we examine the accuracy use – a CMS is after all an appropriate label for a HAT.

It literally assists technical writers author help documents.

As far as pin-pointing what we mean by help exactly – I suppose there are no hard and fast rules as to how broadly you could take that.

It would really depend on:

How deeply the software manufacturers know the technical writing discipline, and;
How persuaded they were to fulfill the need

In most cases, HAT focus on getting the drafting and editorial basics right.

And offer a little, templating, styling and coding on top.

But the question is…

…are these functions alone sufficient enough to meet the steep demands of the modern day technical writer?

Why don’t we just ask a few?…

In this feedback excerpt, the respondent (a technical writer) gives a comparative review of a traditional HAT functionality vs. a traditional CMS (Drupal):

“As an Administrator in Drupal, you can view a list of pages, but you can only edit the properties of one page at a time. There is no multiple-selecting and no drag-and-dropping. So topic management can be very labourious.”

“If you delete a page then all links pointing to it will break, and there are no messages to warn you.

When creating a link in a page you have to know the path and name of the destination page – there are no helpful lists of available pages.”

“Out of the box there is no WYSIWYG editor. For the majority of HAT users this is a must. You can only write your content in full/filtered html.”
(Source: Cherry Leaf)

In this comment, another career technical writer discussed two ideal functions that he thinks would be on trend for the future of HAT software:

“Facted search: when a user clicks the search tab and searches for an item, the user can narrow the search results by using similar facets, as shown in the following image.”

“Using any of the standard authoring tools — Flare, RoboHelp, Author-It, Doc-to-Help — leaves you with the ridiculous model of a single author working from a single vantage point from a single organization trying to pull together an ocean of information. Because that model is untenable and unscalable, HATs will fade in favor of collaborative web-based authoring technologies.”
(Source: I’d Rather Be Writing Blog)

The insights given above expand the remit of the traditional sense of a HAT to include a more dynamic and collaborative platform for enhancing technical writing productivity.

Should you consider using a Component Content Management System (CCMS) for Help Authoring?

Granularity gifts control.

And in the field of technical writing, the advantage of greater control within the production cycle breeds efficiencies that translate into larger project ROI.

This is exactly where a component content management system comes in.

What is a component content management system (CCMS)?

A component content management system is a CMS whose items of content are not pages and posts, but rather snippets, paragraphs and content portions.

So much in the same way when you come to produce a new piece of content in a CMS, you’d start a new page or post.

With a CCMS, you’d start a new component (portion of a page or post).

Many portions make a whole page, so the end result of whole pages and posts is the same, but the way they are made is broken up into small chunks.

Why?

Economies of scale.

Sure it’s arguably more work to build pages based on multiple pieces (each with their own metadata, dependencies etc.) rather than one free flowing whole piece.

But, with large scale complex content projects with lots of topical cross-over and internal referencing the reusability and granular interchangeability on a component level…

…a CCMS offers great long term advantage to writing teams.

Namely, getting things done quicker and more accurately.

What are the main features of a HAT?

So, we’re gradually firming up our view on HATs, what they do and the outside advantages we ought to consider besides the traditional approach.

But it would still be worth us having a comprehensive reference for all the things that a HAT deos.

This way we can compare ‘apples for apples’ when considering an investment choice.

Here is a list of the commonest, most inclusive HAT software functions:

Multiple input and output formats: import and export data using many file types
Fully featured word processor: both code-based and visual WYSIWYG editor
Build tags: assign topical tags to relate articles thematically
Topic templates: get a headstart on every piece with pre-made templates
Syntax highlighter: helpful highlights on grammatical issues to resolve
Merge tags for project wide meta info: insert re-usable snippets with ease using merge tags, savings time and limiting error
Custom HTML, CSS, Javascript: apply tailored touches to function and design with custom web code
Merge project content: combining content within the same project to produce a blended outcome.
Customisable web theme: switches, slides and checkboxes for perfecting the frontend of the tool to improve your user experience
Media repository: a neat storage area for all your images, PDFs, audio and video files
Easy user interface: simple to use with all of the relevant controls in easy to reach distance and positioning
Translation: multiple language delivery
Table of contents: easy to use jump links in each article for skim reading the content

Among the dedicated HATs out there – the points above cover the most part of what would be expected under the hood.

Benefits of building a custom HAT

If I had to summarize the leading benefit of building a custom HAT, I’d say:

Mastery of your own toolset.

Tailored toolset

When you have ‘what you want’, ‘where and how you want it’ as a professional, the return on investment in time saved and improved results is immeasurable.

You simply can’t compare the experience of using tools made ‘just right’ for success vs. a set of generic ‘make do’ instruments.

So customizing your own HAT might involve considerable upfront labour and fuss.

But in the long run the scene is set for you beating your personal best with every project.

Expandable

Waiting for roadmapped improvements, or being squeezed into premium upgrades need not happen with a custom HAT.

Sure, you’ll be responsible for servicing and improving the tool yourself, but for just a little DIY time you can suitably extend the shelf-life of your HAT.

In short, as your HAT gets better, so will your results.

Better all round performance

A custom built HAT will remove all petty or obstructive annoyances from your technical writing workflow.

You remove all bottlenecks and time drains, replacing them with features, options and configurations that gives your race to finishing projects a following wind.

You’ll easily pip what you thought was previously possible.

Making a WordPress Help Authoring Tool with Heroic Knowledge Base Plugin

So, by now if you’re ready to brave new waters and take the plunge into making your own HAT – we’ve got just the solution for you.

Easy to use.

Built on a platform used by more than 40% of all websites online.

With all the best features – plus more.

Here it is…our quick guide on who to make a HAT using WordPress.

And the best part is that there’s no code involved at all. This method is very beginner friendly.

Here’s the line up:

Organising and categorising of pages and files
Search, voting, feedback and analytics
FAQ component replication
Helpdesk for handling enquiries via tickets
Table of Contents page index
Glossary term library

A quick point on “why WordPress”.

For most professionals, having the best tools for the job (regardless of what it’s called) is the most important thing.

Semantics or name calling doesn’t count for much as you become steeped in deliverables and need an engine with some torque to dig you out.

This is where WordPress is ideal as a platform for making a custom HAT.

FIrstly, it ticks all of the essential boxes in the functions line-up mentioned earlier in this article. And it does that with ease, straight out of the box with its core offering.

Features like WYSIWYG and HTML, CSS and JS coding are standard features offered by WordPress (the world’s leading content management system).

But WordPress also hosts a half a trillion dollar hosting, plugin and theme economy.

These players are responsible for delivering the 1st class extensions and performance assistance that make the tool a custom fit for purpose.

All in all, WordPress and its plugin companions make for a dream team offering of a HAT for any technical writer wanting to DIY their own set-up.

Here is an overview of our recommended steps for building your own online marketplace using WordPress:

Directory home page with siloed categories: a hub page serving as your reference library index of completed projects and researched resources. A neat catch-all location for accessing your technical writing log.

Use the Heroic Knowledge Base plugin to produce an automatically linked & itemized line-up of your previously published HAT content.

Search, voting, feedback & analytics: taking note of the call for collaboration from our contributing technical authors from earlier within the article we’ve integrated dynamism and engagement within the features of our WordPress HAT solution. Providing search, feedback and insights will only help develop greater improvements.

Use the Heroic Knowledge Base plugin to enable user research enhancements for directing an iterative improvement roadmap for the product.

FAQ component replication: configure granular component control on frequently asked questions, giving yourself the advantage of having a leaner production for scaling larger projects.

Use Heroic FAQs plugin to gear up your HAT with in-built reusable components with simple install and sero-code.

Heroic Inbox for handling enquiries via tickets: to conveniently field user support tickets giving you a responsive email help channel that sits inside your WordPress install.

Use the Heroic Inbox plugin to integrate your business email inbox into your WordPress admin dashboard. This gives you a unified communications hub within your HAT saving you lost time otherwise spent navigating a disjointed workflow.

Heroic Table of Contents: jumplinks to facilitate skim reading of your articles helps readers digest info and extract value. Make your pieces even more consumable with a classic ToC.

Use the Heroic Table of Contents to add an auto-populating table of contents to each of your articles.

Heroic Glossary: compile an A-Z list of useful terms as a shortcut to accessing definitions of key words on a project, keeping you agile whilst scribing your new project.

Use Heroic Glossary plugin to install a searchable glossary into your WordPress HAT – no sweat, and (again) no code.

Aspose.Words: instantly convert WordPress posts or pages into DOC or DOCX files and vice versa. Bridge the workflow gaps and make your new system compatible with legacy GDocs or Word docs assets.

Use Aspose.Words plugin to enable bidirectional file conversion between WordPress and GDocs or Word.

Syntax Highlighter Evolved: make web code standout as you make custom edits, helping you zone in on the detail without distraction.

Use Syntax Highlighter Evolved to make code beautiful as you make your web savvy edits.

Conclusion

Purpose made HATs in these days of such advanced CMSs are probably reinventing the wheel.

There’s actually not a lot (if anything) that even the most advanced featured HAT can do that a CMS with some config couldn’t do.

Plus, with a CMS, you have additional functionality which adds advantage to an already competitive offering.

The further potential provided by a CMS (the market leading WordPress with its plugins) can extend a like-for-like HAT solution beyond what your expectations.

Plenty of room to scratch your own itches and continue innovating with WordPress – plus no coding necessary.

A rapidly expanding 3rd party plugin ecosystem supports WordPress’s marketshare advantage with specialized products to push the boundaries of possibility.

All in all, we’re persuaded that if you are looking to make a future proof custom HAT investment, WordPress CMS is the ideal digital platform.

Why not start today?