My philosophy: any effective documentation or training content first needs to be easily accessible by the user exactly when and how they need it, and easily understood by that user at a glance.
Content Taxonomy
Effective content taxonomy not only ensures users can find the content they’re looking for via search engine optimization (SEO), but depending on the content management system (CMS) you’re using, it can also power everything from ‘related topics’ lists to fully integrated contextual help articles within a software application.
I designed one such contextual help implementation for a software product using a cascading taxonomy. In this taxonomy (represented in the image below), the system would start at the most granular level of content associated with the task the user was performing at the time they clicked the help button. If there was no content associated at that level, it would instead look for content related to the workflow the task was a part of, and so on up the hierarchy.
This system ensured that the most relevant content available would always be displayed to the user. As new articles were added to the CMS, the underlying architecture never had to be updated so long as the same taxonomy was used to categorize new content.
In addition to this primary cascading taxonomy, I also designed a robust metadata and tagging system that was used by other functionality within the CMS, such as automatically associating related articles to one another and ensuring articles were searchable by related terms, even if the term wasn’t in the content of the article itself.
Style Guides
A style guide is a living document that helps to ensure consistency and clarity throughout various channels of content. This can include things like branding guides, terminology glossaries, and other general rules to set consistent writing and visual standards.
As a small example, in one project I was on I often used callouts within articles and courses to draw attention to specific types of information, but I had different styles I wanted users to associate with ‘informational’ notes vs. ‘warning’ notes. That’s the type of thing I always made sure to document in the project style guide; in this case, noting that a ‘warning’ note and an ‘informational’ note were each associated with a specific color and icon, and providing guidance on which common scenarios would use which note type.
Even on projects where I was a team of one, I’ve always created and maintained a style guide as part of my development process. For larger projects with multiple contributors, this sometimes expanded into creating a style board – a regular meeting of content contributors across the project to discuss updates or additions to the style guide.
Help Center Example
In a recent project I led, I created an entire software application help center from scratch. This meant designing all aspects of the content strategy, from the site structure, to the page layouts, to the visual design. The CMS I used in this example was MadCap Flare. There’s a lot I was able to do out of the box with Flare, but some elements of the site design required me to create custom front-end scripting (using Javascript, alongside custom CSS).
As the Help Center for a software product, the primary content of the site was task-based help articles giving step-by-step instructions for how to use various features within the application. The main layout I designed for this type of article included a collapsible right panel (coded using custom Javascript and CSS) and an initially condensed view of the steps in each task which could then be expanded for more details. Because this was such a complex application, I chose this approach so that the user would not be immediately overwhelmed with information but would still have full control to go as deep into the steps as needed.
We also had a specific use case on this project for a regularly updated list of known issues within the application. There were at any given time upwards of a hundred individual items on the list, so it was a challenge to display them all in a way that was still accessible to the user. The solution I came up with was a custom filterable table (coded using custom Javascript and CSS). I also created a separate custom mobile version of the list that would display at specific breakpoints, so that the content would still be accessible on smaller screens that could not display the full table view.
