Start with an intuitive UI

Mainstream apps mostly get this right. They focus on limited tasks that users already want to perform, and the interface is simple enough to always provide the next intuitive steps without distractions.

As systems solve more proprietary problems, their interfaces and capabilities become less intuitive and less simple. Although the legacy of documentation has evolved since computing became mainstream, users still need need documentation to fill their knowledge gaps. If this fails, the burden falls on customer support functions.

Create self-help support

Uncertainty can strike for your users at many stages of their learning journey. Directly supporting all your uncertain users with human helpers can be costly, so self-help documentation reduces your burden. Some organisations separate these self-help needs into distinct channels:

• Presales content, for prospective customers to learn about your offering.
• Training content, for customers to learn journeys or configure your product.
• Community content, for non-authoritative solutions.
• Technical content
  • Concepts, to outline product abstractions.
  • Immediate tasks, for established users while they perform tasks for the first time.
  • Reference, for users who want to find data or structure in your product.

Although users take support from documentation in many ways, this article addresses technical content, where users take the journey from the app to your content.

To support a smooth journey to success, you have to know who you're helping: what knowledge they have, what skills they bring, and what they need to know to perform tasks in your product.

Provide help close to the user

As systems become more proprietary, the gap increases between a new customer's knowledge and what they need to use your product.

That gap needs explaining in the product UI, or in documentation. Training and solutions teams can help onboard your customers, but you need to back that up with self-serve content, either as a reminder of their training, or to help them grow with your product.

The best user experiences enable your users to be productive and achieve their business goals quickly. This means that a perfect experience is one where your users spend very little time with your software, or get lots of specialized work done efficiently, all while never falling back on extra help.

However, we know that intuitive interfaces are hard to design for complex solutions, and that's where content writers can design help where it's needed, using appropriate UX devices and content. Although users can search your help site, users need direct access to help content, relevant to their role and context in the UI.

Try to keep help as close to the UI as possible. These options for self-help are progressively more distanced from the user:

• UI text that is clear and concise. Field names, UI sections, and hints are meaningful.
• Short narrative, for areas that need a paragraph in the UI.
• Expandable content within the UI, where longer description will help the user.
• Concise links to online help documentation, for in-depth concept narrative, or task steps.
• A context-aware help link
• A link to all documentation, where the user can search.
• Offline documents, like PDFs or Word files.
• Printed manuals.

Create help to match the needs of your users

Here are some situations that need different types of help:

1. Your product is intuitive enough that your customers use it efficiently, and they never need help.

   You've succeeded with a perfect product. You only need documentation if you're contractually obliged, or you want training content.

2. Your customer selects a help button for a small part of the product, briefly reads a short page of documentation, then uses the product as intended.

   Perhaps the core UX is not as guiding and intuitive as it needs to be. However, you've decided that a clean UX means moving some content to a dedicated help site.

3. You need to walk a customer through steps of a small process.

   Perhaps your users arrive without knowing the capabilities of your product, how to prepare for a task, how to complete a task, or what they can do with the results. You need tutorials or task articles.

4. You need to explain concepts that help the customer understand how to use your solution.

   Perhaps the abstractions in your product are not clear for the user. You need concept articles, with sub-articles to explain related tasks and reference data.

5. You have many choices available for a data item, but without specialist knowledge, it's hard to understand what they are.

   You need reference content, either as embedded metadata in your UI, or as online reference.

For large products, you'll likely need all of these.

Use technical content writers

Technical writers are your word experts. They know your user's perspective, skills, goals, and how to use the product for success.

Ideally, everyone in product, design, and engineering has technical content skills. Technical content skills are too big to be a part of everyone's role description, so technical writers create and review that content consistently, wherever it is needed.

The best technical writers will make technical documentation obsolete through collaboration with product and UX designers. Where that's not possible, they create the words and patterns that enable the best customer experience.

For the best user experience, technical writers need to:

• Be present at the start of your product and feature life cycle, to learn about the feature and the user's roles and skills, understand where users need help, and plan new customer-readable information into existing documentation.
• Advise on the right level of help, with customer advocates and UX researchers.
• Collaborate with marketing, pre-sales, and customer success functions, learn and advise on key messaging, and help ensure this is clear in context of the product portfolio.
• Assist UX designers, review their text content, and provide supplemental content.
• Be available to software engineers, to review and advise on any customer-facing text content. Ideally, this content is a uniform data resource that is managed for translation and release.
• Set consistent and appropriate tone and style of words.
• Never be afraid to constructively highlight a poor user experience, even when the solution design seems final.
• Work with product managers to establish entry points to documentation, including effective search results, and for that content to be available at feature release.
• Be proactive, and responsive to research, feedback, and analytical data, about the success of the content and usability of the product. Remember that fewer hits could indicate a successful user experience, poor feature adoption, or that your content is not discoverable.