Technical documentation belongs on the web. Unless your product is top secret or your customers can’t access the Internet, you need to make an effort to get your content online. Doing so will greatly increase your customer’s ability to use the product while decreasing the amount of costly support calls made to your support engineers. But simply outputting your dry, stuffy manuals and guides into framed HTML or PDF isn’t enough anymore.
These days, help and technical documentation is as much about videos, forum posts, and blogs as it is about concepts, reference, and tasks. When put together and combined in a simple, effective way, this content can form a useful customer support portal: a one stop shop that will enable your customers to help themselves.
What Makes An Effective Customer Portal?
Who are your users? What are they having trouble with? What kinds of answers are they looking for? Although there is a way to get answers for these questions, the best answer is probably this: there is no single user type, your users probably experience the same set of recurring pain points, and every user consumes content differently.
A good portal satisfies a number of different types of users by providing a thoughtful, easy to search and easy to navigate set of information in a variety of formats. A good portal provides documentation, videos, blog entries, and forum posts and serves them in a simple and effective fashion.
In addition to a simple, professional overall design, your portal should consist of the following things:
Documentation is the richest form of help content, however it can also be the driest and most intimidating. Nobody wants to spend time reading through your documentation, especially when they have a problem that needs fixing ASAP.
When creating your documentation set, consider the following:
- Ensure that the help set is written in the correct tone. Use plain language and simple terms.
- Structure your content properly:
- Organize your content by task where applicable.
- Follow industry standards by creating topic, task, and reference topics and make sure that your content is organized properly.
- Avoid the wall of text by breaking up complex topics or using graphics or tables where applicable.
- Be consistent. Use parallelism where possible.
- Provide proper navigation. If possible, use a left pane table of contents to define the hierarchy of the content. Use landing pages to demarcate categories, important concepts or books. Also provide a breadcrumb trail to allow the user to retrace their steps.
Navigation not only allows your users to move back and forth within the content, it also provides context for the hierarchy of the help set. Below, the Android Developer online portal uses an effective left hand navigation as well as a top level navigation menu.
According to Cisco, by 2019, 80% of internet traffic will be video. Internet videos are so commonplace now that some users expect them.
Videos are ideal for providing high level overviews of complicated concepts or for providing a guided tour of an important feature. With tools like Camtasia that allow you to storyboard your video, record your screen, and overdub audio, creating a YouTube hosted playlist of professional looking videos is easy.
While technical documentation is great for traditional user documentation, a blog is a great way to casually describe a new feature, introduce a concept, or walk through a given scenario. When written in a casual tone, and attributed to a credible persona (for example, when written by a developer or evangelist and given an associated avatar, title or bio), a blog article will disarm an already annoyed user. A blog is great for that piece of content that can stand by itself, that can be shared easily, that is both timely and timeless, and that you don’t want to bury in the rest of your documentation.
Community and Social Media
A forum gives a voice to your customers and answers their questions while creating a moderated, searchable knowledge base. An active developer community will pay for itself in fewer support calls while persuading potential customers that your current user base is active, productive, and ultimately happy.
Twitter might be the easiest and most pervasive tool for broadcasting to a large number of users. You can tweet product releases, news, and general announcements. Conversely, many companies have utilized twitter as a casual, lightweight support mechanism. You can tweet a question to support desk and expect a response back quickly.
Everybody has a Facebook page.
Tying it all together
Just having an effective set of well-organized content is one thing, but how do you tie all of the different types of information together? How do you serve it up to your users? How can your users find what they’re looking for when what they’re looking for spans videos, forum posts, documentation and a blog?
Some of your users will use the navigation to find what they are looking for. All of them will use the search. When your content is a varied mix of videos and text, you need to provide a unified search that spans all domains and formats and organizes search results accordingly. A unified, or federated search, will search your entire site’s contents, returning everything in a categorized list.
A faceted search provides a tabbed interface that lists all search results by taxonomy, enabling the user to easily find what he or she is looking for in the format in which they want to consume it. The TED website uses a very simple and effective faceted search:
Metadata: Building Dynamic Views of Content
Metadata is defined by Merriam-Webster as “data that provides information about other data”. It is the information embedded within a document that enables you to build powerful content. When used properly, metadata is a powerful tool that can greatly improve the effectiveness of your search engine while simplifying and improving your navigation.
One of the most natural ways to use metadata is to build a taxonomy, then use that taxonomy to provide dynamic views of your content. Put simply, you can embed keywords into your documentation topics, videos, blog posts, and forum topics, then use the metadata in those keywords to dynamically render a single view of all related information at once. Put even simpler: Show every related thing at once. In the Klocwork Insight documentation below, metadata is used to render a list of related videos and blog entries for documentation topics that share the same metadata:
The days of RTFM are over. You can no longer upload your dry technical documentation online and expect people to read it. Users want to watch videos, walk through sample source code, pose questions, and read expert blog posts. They need a customer support portal.
If done correctly, a portal combines a variety of related but disparate information into a single, intuitive, consistent, consumable experience. Providing this information, and doing so in a simple, pleasant and intuitive way, will improve your customer’s experience and satisfaction and decrease the amount of costly phone calls made to your support engineers.
If customer satisfaction and goodwill is not enough reason to create a portal, then consider this: an effective online portal will increase your product’s brand. By building a well-branded, effective portal, you can improve your online presence and make your user community happy, vocal, and engaged. While it may not sell your product for you, it will show potential customers that you have an active user base, and that you care about user experience.
The Impact Technical Writers Can Have on User experience | Blog
An organization understands that Technical Writers are skilled in delivering quality documents for...
How to Benefit from Working with Technical Subject Matter Experts (SME)
Technical SMEs, pronounced ‘smees’ stands for Subject Matter Experts. Many of our projects require...
how project managers create better learning
A certified project management professional has expertise in key areas that help to ensure a...