Write Better Help Documentation with These UX Tips


For a while now, there has been some attempt to reconcile the need for help documentation with the growing desire to improve product UX. True to Don Norman’s famous statement that “If you have to hang a sign on it, you’ve lost the battle”, many user experience professionals try to solve interface challenges using purely design solutions.


Today we know that product reality is more layered than that. Not everything can be solved through design alone, and almost nothing can be learned without any text. In a sense, we are no longer simply writing the support documentation – we are designing the support experience.


As part of that process, help documentation was brought out of its exile in forelone knowledgbases on the fringe of things and now resides in the heart of the user experience: in microlearning, onboarding flows, quick-tips, mouse-over tips, lightboxes and help widgets.


But we’re not quite there yet. There is still some way to go before the melding of help content and product UI is complete. I hope these UX insights and tools improve help documentation and user engagement with it.


ux tips for tech comm stock woman in front of color board

Acquiring Skills and Expanding Your Professional Repertoire

I’d like to start by recommending an article which I believe will become canonical  for anyone in the content professions: Rise of the UX Writer, by Ben Moran. “Rise” is one of the most important essays to have been published recently on the shifting ground beneath the feet of digital writers.


Moran makes a compelling case for migration toward new professional paradigms. He recommends copy writers get more involved in the UX design stage of product development, impacting the user experience, melding text and design into a more powerful, smoother user experience.


Needless to say, this approach applies tenfold to technical communicators and support professionals. Technical Communicators need to start inserting themselves into earlier stages of the product design, to ensure a holistic, intelligent approach to help and onboarding. Expanding one’s professional repertoire also means obtaining new skills and mastering at least some of the variety of technical writing tools now available. In other words – staying relevant and ahead of the curve is crucial to surviving, not to mention thriving in this rocky terrain.


Distill Your Help Content’s Style & Tone of Voice

One of the more critical stages in UX planning is asking oneself: who am I writing for? And what am I trying to get across? UX professionals address this by creating user personas. These are fictional personas that resemble your end users, and giving them a voice and characteristics helps us to get to know our users a bit more.


By giving our users a face and personality, we better understand what they are expecting from their help content, their needs, technical grade and attention span.


Microcopy guru Kinneret Yifrah recommends adding a series of “what would” questions to add credibility and substance to your personas: Which operating system does my user prefer? Which smartphone brand? Where would she prefer to spend a quiet evening?


I’ve created a few basic examples of tech-comm personas which you can download.


user persona template for help documentation

Right-click image to download


Style Guides

Software giants like Salesforce work with carefully crafted style guides that help to decipher tone and character (as well as nuances like ampersand usage and a million other grammar and syntax issues that writing geeks like yours truly devour greedily).


In this neat example from Salesforce Trailhead knowledge center, Salesforce exhibit a somewhat surprising tone – it is light, playful and very visibly intended to put the reader at ease:


Now at this moment, you might be looking at that Criteria column and thinking, what does all of that mean? Rest assured, we’ll cover those topics in detail as you work toward earning your badge for this module.”

Create a Consistent, Fluent Terminology

Often in the process of developing a product, somewhere between planning, design, R&D and QA – a variety of new terms are born to describe actions and features. Sometimes multiple names are coined for the same objects. You can always tell which ones were invented by software developers and which ones by copy writers.


In addition to consolidation of terms across the product – in menu items, on buttons and inside the platform, it’s important to make sure you’re using the same terms to describe generic actions. “Add”, “Activate” and “Resume” can easily be interchanged with “Insert”, “Start” and “Return to”.


There’s no need to invent the wheel (unless it’s part of your product team’s disruptive strategy). It helps to stick to familiar terms from the neighboring industries.


We feel this keenly in the onboarding industry. The digital training industry is laden with terms to describe very similar features: widgets, lightboxes, inline help, tooltips, and so much more. Over time, most onboarding solution providers got on the same page regarding the terms and hopefully users today are making more sense out of the rich terminology.



Design your Content to be Readable and Accessible

Something that comes naturally to designers but does not (yet) to writers – the way text is designed impacts the reading experience more than anything else.


I’m not talking about typography (although selecting a highly readable font is definitely part of the deal) – this is about spacing, aligning text, creating short, digestible paragraphs and organizing everything under helpful headlines:


  • Spacing
  • Align Text
  • Short, digestible paragraphs
  • Headlines
  • Use bullets


If you’re creating tooltips or designing microlearning content, it is perfectly acceptable to highlight certain words in bold, in order to help them stand out.

Adobe’s user guide give a fine example of well-spaced, visually engaging


adobe knowledgebase



I can hear the minor panic attacks fluttering throughout the readers of this article. “Colors?! That’s something DEISGNERS do. I couldn’t tell beige from mother-of-pearl if my life depended on it.”


Well, you’ll be happy to hear you won’t have to. Designer Marc Hemeon put together a brilliant piece, aptly named: How to not suck at design, a 5 minute guide for the non-designer. That’s really all you need to get through some color-assisted help content.


And if you still have doubts, take a look at this tooltip, screenshot from a Salesforce tutorial that popped up for millions of users. If they can pull off something so basic and frill-free – the rest of us can, too.


salesforce yellow tooltip


Of course, you can aim a bit higher, like in customized Iridize-powered product release, but that may require some real-designer assistance:


iridize designed release note with cta


The human brain responds more favorably to some numbers, more than to others. Obviously, if a certain action takes 4 steps – it won’t do to simply ignore one step in order to fit the whole thing into a Magical 3-Step article. But if the action itself is flexible – why not appeal to basic cognitive functions and get higher conversion rates?


The Slack Help Center is by far the best arranged, designed and planned I’ve seen and exhibits a terrific blend of item numbers (3 bullets), spacing, bold text and use of colors. Notice that even the warning box stands out in a way that isn’t intimidating or actually alarming.


Screenshot from Slack help center

Help your Users Regain Control and Stay Oriented

As help providers, it is part of our responsibility to help our users stay in control of their environment. Seeking help is in itself an admission of insecurity and disorientation, and regaining a sense of control over your surroundings is a critical part of the process.


Users’ need to manage their time and expectations with regard to content length/duration has been addressed for a while now in content platforms all over. Medium’s ‘X min read’ is the most well-known example.


Salesforce’s Reports & Dashboards module offer a reading duration estimate for each chapter of the guide, allowing the user to decide when and how she wants to invest her resources.


salesforce reports and dashboards menu


Time/reading duration is one way to provide context. There are other, more creative methods that help to manage expectations with regard to orientation in a specific help flow. The most common practice in context-sensitive help is to tell the user how many steps the guide includes and which step they are currently on.


Iridize context sensitive help


MailChimp took it a step further and created a visual indication of their table of contents scroll. An awesome thing to have, when you have their resources:




To sum up the examples, help documentation has come a long way since the days of endless PDF databases that would sometimes require a manual just to get through them.


We are privileged to be surrounded by smart, creative examples of content delivery methods. The essence of user experience is about optimizing delivery and presentation in a way that would make our users more comfortable around help resources and as a result – around the product.


Discover new ways to improve UX in your help content

Write better help content


Noa is Iridize's Head of Content. With a background in digital strategy planning and database management, Noa translates Iridize's vision, stories and data into words. Digital learning and user experience are a particular passion of hers.