Introductory guide to user documentation with links to further reading

In this post we’re going to give you a broad-strokes introduction to user documentation with links to more in-depth articles on specific topics.

Contents

1. Knowledge base definition
2. What is user documentation?
3. Who writes documentation?
4. User docs vs developer docs
5. Defining the user
6. What does user documentation look like?
7. Building a knowledge base
8. Knowledge base software
9. Information architecture
10. User Experience
11. User research
12. Creating content
13. Inclusivity and accessibility
14. Writing documentation
15. Driving traffic to your your knowledge base
16. Knowledge base naming conventions
17. Documentation team
18. Business function
19. Documentation and marketing
20. Customer feedback
21. Knowledge base metrics
    
    

1. What is user documentation?

Write the Docs has published a fantastic guide to the principles of documentation.

Definitions are difficult because documentation is a huge field comprising a variety of expertise and skills. This terminology has its roots in developer (or system administrator) documentation for software, and is intertwined closely with many technical tools used in the software engineering field.

Wikiversity makes the clear distinction between documentation for system administrators and the end user. But really, user documentation is aimed at the end user of any product. This product could be categorized as software, hardware, appliance, sports equipment, vehicle – literally anything that requires documentation before someone can use it properly.

Photo by Bernard Hermant on Unsplash

For many companies, their documentation is hosted on an online knowledge base – for reasons of both practicality, cost and user convenience.

2. Who writes documentation?

If your job is to produce documentation, you are probably a technical writer. This may not be your only role. Additionally, anyone can write documentation.

Contrary to popular opinion, you don’t necessarily need any further specialist expertise to write for users – as professional technical writers well know. You do, however, need a close affinity for the user and a tenacious ability to draw information out of your colleagues.

You do need a particular skill set if you want to write developer documentation – specifically, some development skills. Developer documentation is still user documentation but it falls into its own category of content, since it’s most likely produced by writers with an engineering background (again, not necessarily).

That being said, technical writer is still a profession with a specialist skill set with requirements stemming from many overlapping disciplines. Technical writers are generalists.

There is a huge industry of technical writers out there. Some popular conferences for technical writers are Write the Docs and Soap!. Check out this open source list of tech comm conferences.

3. User docs vs developer docs

It’s useful to have a distinct category of user documentation compared to software documentation – even though they both involve users. This is partly because developers have different expectations when it comes to documentation.

With user documentation, you can be a lot more conversational and casual. This approach will likely just annoy developers – they usually want you to just get straight to the point with minimal fuss. That being said, you can’t go wrong with really well designed developer-focused docs like Stripe and Twilio.

Developer documentation will also usually take a slightly different form, including Quickstart guides, tutorials, API references and troubleshooting.

4. Defining the user

User documentation is interesting because the user could literally be anyone – but in each specific case it’s the user of your product.

Sometimes it’s difficult to build an accurate image of your user – especially in tech comm – and technical writer Tom Johnson has written an excellent article on reconstructing the absent user.

Who your user is could be different from moment to moment and in differing contexts. The user of documentation is not also not necessarily the same person who initially bought your product.

Technical writers are used to foraging for information. Here are some indirect ways to reconstruct the user:

• Web analytics
• Surveys
• Support tickets and user forums
• Customer milestones completions
• Customer satisfaction scores

This list was defined by technical writer Tom Johnson.

We’ll also add:

• User comments on documentation
• Conversations with customers and support folks
• Product reviews

5. What does user documentation look like?

Documentation can range from anything like a one-pager FAQs for a product, to a huge library of documentation.

Documentation is defined by TechTarget as:

“In the computer industry, documentation is the information provided to a customer or other users about a product or the process of preparing it.”

Software in particular often needs a huge range of documentation. The documentation you need to produce will determine the type of software you should use.

Documentation taxonomy

Types of documentation:

• Tutorials
• How-to-guides
• Explanations
• Reference

Daniel Procida, Technical Writer at Divio, gave a talk on documentation taxonomy along these lines – specifically in relation to software.

For API documentation, we would also add ‘Quickstart guides’ to this list.   

6. Building a knowledge base

We’ve published a Great Knowledge Base Design Cycle to help you go from zero content to knowledge base superstardom!

The cycle provides a framework for you to quickly create and iterate on your documentation in order to best serve the needs of your customers.

The six stages are:

• Need – Identify the purpose of your knowledge base
• Outline – What are you going to cover with your content?
• Write – Fill in the outlines by writing knowledge base articles
• Publish – Publish and promote your articles in front of your target audience
• Report – Measure success by tracking metrics and feedback
• Act – Iterate on your knowledge base by continually improving

Sounds easy, right? Check out these best practices that ensure your knowledge base is awesome, and find out how to get started writing user docs.

Aim for good enough – not perfect! Technical Writer Neal Kaplan has given a fantastic talk on the art of documentation triage.

7. Tools for user documentation

There are many specialist tools for technical writing, some of them popular in the tech comm industry. We make a distinction between the documentation field, with its roots in software, and the discipline of technical communication with its history in academia.

The most basic documentation can easily be incorporated into your regular CMS, and could perhaps live as part of your company or product website.

Most companies find that once they start getting serious about their documentation strategy, they require tools that come with more sophisticated Information Architecture. This has led to a plethora of specialist documentation and knowledge base tools.

There’s more on this in section 8.

Help authoring tools

Some help authoring tools such as MadCap Flare and Adobe FrameMaker are popular with large teams in certain industries. These are more complex than your standard knowledge base software. They’re more suitable for publishing technical communication on a variety of platforms – including both print and digital.

Another reason enterprise teams prefer these tools is because their content is often published in markup languages like Markdown (tagging systems for formatting documentation). Markup languages enable easy publishing and reuse of content across different platforms.

As a side-effect, enterprise technical communication teams are often struggling with legacy systems – even though theoretically better software may be available. These tools usually have a large number of features, a hefty price tag, and are not suitable for every company.

8. Knowledge base software

Many companies benefit from using standalone knowledge base software. There are a few different types, which can be confusing at first.

Knowledge base software can come bundled in with full-stack helpdesk solutions like Kayako, Zendesk, Confluence or Freshdesk.

Companies may not need the whole helpdesk, or they may be happy with their existing helpdesk and only require a dedicated knowledge base solution. A few different options have sprung up to meet this demand, including:

• Helpjuice
• HelpDocs
• Document360
• KnowledgeOwl

Our very own KnowledgeOwl is a light-touch Software as a Service (SaaS) knowledge base solution. The CMS is easy to use, getting you up and running right away.

Check out our post comparing the different SaaS knowledge base solutions, and learn how to compare knowledge base software. The main differences between solutions are available features, pricing, number of users, and level of customer support.

Open source knowledge base solutions provide different benefits. A general rule is that open source solutions require more development investment and are not necessarily “free” (as in no cost). You will have control over the code – to some extent.

Knowledge base software reviews are available on comparison websites like GetApp, G2 Crowd, and Capterra.

9. Information Architecture

According to the Information Architecture Institute:

“Information architecture is the practice of deciding how to arrange the parts of something to be understandable.”

Image: Users have to make a choice every time they take another step in your knowledge base

Information Architecture (IA) is a key part of UX design. We wrote a whole post on Information Architecture for your knowledge base.

Elements of Information Architecture are:

• Visual hierarchy – size, color, contrast, alignment, weighting
• Navigational menus including main menu, sidebar and sitemap
• Breadcrumbs to show place in the navigation
• Task sequences ordered by related steps
• Tagging with keywords to signify related content
• Contents menu to break down long content
• System of order – alphabetical, numerical, chronological, topical
• Labelling as a shorthand for complexity
• Categories – broad top-level categories and niche subcategories

Information Architecture and software

You don’t have to bear the burden of designing all of this Information Architecture yourself. Some parts will be specific to your company, but knowledge base software comes with many of these elements pre-built.

You can host documentation on your company website, but extensive documentation requires IA that just isn’t provided with a standard website CMS. There are standardized templates for company websites, blogs and ecommerce sites, in the same way there are knowledge base templates.

Once you get to a certain level of ecommerce operation, a standard website template with an ecommerce plugin may not cut it. This leads many companies to opt for solutions like Shopify and Magento for their enhanced capabilities.

In the same way, a central reason why you might use knowledge base software instead of a standard CMS like WordPress, Drupal or Squarespace is a desire to scale.

Searchability and findability

Information Architecture relates closely to making your content findable.

Can your users browse through your content and easily discover related topics, or find a section they were in previously? Does your choice of categorization tell them where content is likely to be?

As well as creating a system for users to follow, you need to make your knowledge base searchable, and tag your content with relevant keywords.

Topic-based authoring

Topic-based authoring in documentation stems from the DITA methodology. DITA (Darwin Information Typing Architecture) is a proprietary information system owned by IBM based on XML.

But topic-based authoring is simple to get started with. We like to think of as ‘chunking’. This means you structure your content as building blocks that can stand alone, and also form part of a larger whole.

It means documenting specific tasks as modules – as opposed to a thorough, long, A-Z manual with a contents page. It’s partly useful because in online knowledge bases, users will be arriving to your content from many different directions. They may not necessarily hit the homepage first, so each and every page has to be a gateway to deeper inside the knowledge base.

Chunking your content into reusable topics is effective as long as you organise it properly with Information Architecture, so users are empowered to browse your content.

It’s related to the Just In Time methodology for producing documentation. Similarly, you can refer to the Every Page is Page One methodology popularized by technical writer Mark Baker.

10. User Experience

User Experience (UX) design means designing for the needs and goals of your users as best fits your organisation’s objectives. It’s closely related to Interaction Design and User-Centred Design.

This shouldn’t be a brainwave, and at KnowledgeOwl this is the foundation of everything we do.

So what are a user’s goals? In the case of knowledge base design, the users wants to fix a problem with your product or to accomplish a task they don’t yet understand.

Factors that influence good UX:

Image credit: Peter Morville

Your documentation should be useful, usable, desirable, valuable, findable, accessible and credible. 

Documentation UX has no hard and fast rules, but it’s all about fulfilling expectations.

Documentation UX principles:

• Keep it simple, stupid (KISS)
• Make content easy to scan
• Interlink as much as you can
• Use contrasting colors that are easy on the eyes
• Make navigation prominent, easy and consistent
• Make use of white space

Here are five tips on knowledge base UX design to optimize for user success.

Design

The visual design of your knowledge base will use the same principles as any other website.  Web design techniques are based on trends that evolve over time – what looks great today may be hopelessly out of fashion next year.

Your knowledge base design cannot be separated from the UX. There are certain primarily visual brand elements like color schemes, font choices, font weights and logos, and these will be part of your marketing collateral.

But good design doesn’t just mean making your knowledge base look good. It’s about fulfilling your original purpose – to help your users self-serve.

11. User research

User research is defined as:

“The practice of studying users’ behaviors and motivations to understand more about their needs.”

To design effectively, you need hard data to govern your decisions and that can take the form of user research. Research is helpful, but it can be time-intensive and complicated. It’s easy to get it wrong if you’re not sure what you’re doing.

Remember these principles before conducting your user research:

• Beware of the curse of knowledge (your own bias)
• Make it the responsibility of a whole team (it’s too much for one person)
• Plan your research in advance (it will take longer than you think)
• Aim for five participants (this is enough)
• Allow your subjects to fill silences (don’t talk too much)
• Research continuously (rather than at the start of a project)
• Find out what you don’t know that you don’t know (test your assumptions)
• Use paper prototypes (sometimes your app isn’t ready yet)
• Bear in mind users being observed will change their behavior (the Hawthorne effect)
• Distinguish between user wants and user needs

Jennifer Lambourne from the UK’s Government Digital Services talks about exactly how to make your user research projects a success.

12. Creating content

Content is the foundation stone of your documentation activities. You can do everything else, but if you don’t have good content then your efforts will be in vain.

According to Write the Docs:

“Content” is the conceptual information within documentation.

Good content is defined as content that meets your objectives. Here’s a laundry list of good content features:

• ARID – Accept some Repetition In Documentation
• Skimmable – Structured properly so that users can skim
• Exemplary – Use examples and tutorials to help users save time
• Consistent – Consistent language and formatting
• Current – Out of date documentation is worse than no documentation

This list was defined by Write the Docs.

Multimedia content

Content usually takes written form but can also be video, screencast, screenshot and other imagery. Audio is rarely used.

There are mixed opinions on the importance of multimedia content like screenshots and screencasts.

On the one hand, visual content can improve the learning experience and help simplify a complex process. On the other hand, it’s costly and time-intensive to maintain in case your product or interface changes, and is not accessible to blind or partially-sighted users.

A good rule of thumb is to try to accommodate both. Make your text content stand alone, but include optional imagery.

13. Inclusivity and accessibility  

It’s important to consider a variety of use cases and users when producing documentation. You should also write for users who are not yourself. A common flaw in documentation is to write for a white, western male audience since these people are often the primary creators of popular products (and often their most vocal users).

For example, you may write for a native Western audience, but a large proportion of your users are in India. You may refer to your users as ‘he’ when in reality they are a mix of genders. You may assume things about a user’s prior knowledge. 

A best practice for documentation inclusivity is to avoid idioms that may be confusing to non-native speakers, use plain language, use gender-neutral pronouns and job titles, and avoid ‘jokes’. If you must make an in-joke, provide a link to a reference.

Accessibility

Accessibility is related to inclusivity and relates to users having various needs with regards to your documentation. Accessibility is a legal requirement and the W3 has extensive guidelines on accessibility in web design.

For example, partially sighted or blind users may use screen readers to convert the text to audio. Imagery will not register with these tools unless it has ‘Alt text’. Another example is having captions in videos for hearing-impaired people.

14. Writing documentation

Writing documentation for your knowledge base involves making definitive choices about the words, grammar and style that you use.

Documentation writing should be direct and to the point. Even more so for developer docs. Don’t be afraid of repeating terms if this keeps the meaning clear.

You should be aiming for:

• Concise representation
• Clear meaning
• Direct approach
• Semi-formal and neutral tone
• Natural style

As a rule, stay away from marketing copywriting techniques like using dynamic verbs and adjectives, and storytelling. The ‘personality’ that should come across in your docs should be subtle at most, absent at the very least.

Here are some best practices for writing knowledge base articles.

Brand voice and style guide

The brand voice and the style that you write your knowledge base content in will vary from company to company. You should have brand guidelines for all content – including documentation. Tone of voice is crucial in keeping your content consistent and on brand.

Brand guidelines are not just for marketing. It’s about creating a unified impression of your brand across all written and visual content. It doesn’t have to be cheesy or fake – think of brand as the sum of your company’s individual people and parts that the wider public will relate to.

Having a strong brand in your documentation is great for building trust with your users. It helps them learn what to expect and identify content as part of your company.

Plain language

Plain language is an important writing practice which means removing any unnecessary elements in your writing. User documentation should be written in plain language.

Plain language is defined as:

“Communication your audience can understand the first time they read or hear it.”

Plain language principles:

• Choose common, everyday words
• Choose the most apt words possible
• Write in short sentences
• Order concepts and meaning in logical fashion
• Use “You” and other pronouns
• Use the active voice

It means getting close to the reader and writing from their perspective.

This opposes the usual tendency in technical and academic writing to write in a very formal register. Writing in a formal register means employing long words when a short one would do. It uses complex sentences constructions when you could write simple sentences with single clauses. People have to work harder to read it.

It’s a rule for life, and not just for documentation!

15. Driving traffic to your knowledge base

Driving traffic to your knowledge base is all part of your customer support strategy. You cannot publish a knowledge base and expect your customers to find it.

Search Engine Optimization is one way to get traffic to your knowledge base. Some of your existing customers may prefer to find content this way.

For the rest, you can:

• Emphasize your knowledge base on your website or in-app
• Train your support team to suggest content when responding to tickets
• Include new content in your newsletter
• Link from your blog posts like tutorials
• If you're sending out printed manuals, include a link to your knowledge base

Over time, your customers will become used to turning to your knowledge base for help and this will grow traffic.

16. Knowledge base naming conventions

You may have noticed that company knowledge bases are not always called such. This is an industry term, and a knowledge base may be labelled differently out in the wild.

Some examples of knowledge base labels:

• Help / Help center
• Support
• Docs / Documentation
• FAQs

A good rule of thumb is to copy whatever the standard is in your industry. Navigation labels are not a place to get fancy.

Debate has raged over whether the correct term is knowledgebase or knowledge base. We prefer knowledge base as that’s surfaced as the most common.

17. Documentation teams

Depending on your industry, you may or may not have a documentation team. Some companies may be lucky to have just one technical writer on staff. Others may have a whole team of documentation writers.

Matters are complicated by the fact that different businesses may use different names for their docs team. Some even have a Customer Experience team, of which documentation will be a part.

Technical writers may be embedded in the development team, customer support, or product team. Rarely will they be part of marketing. Some businesses make their entire company responsible for documentation.  

If you’re going to scale your documentation strategy, a team is essential.

Docs Like Code

If you operate a Docs like Code approach to documentation, your technical writers may well be embedded with engineering. In this methodology, the documentation lives in the same codebase and uses the same tools as the software code. This only applies to companies that develop software products.

It also means use the same development methodologies such as Agile and Test Driven Development.

18. Business function

Internal teams are usually structured according to the business function they serve. Several teams may have at least a partial responsibility for documentation.

Many companies differ on which arm of the business to place documentation. Some view it as a subset of Customer Support. Others still as a part of Product. Some larger companies are legally obliged to provide complex documentation and view it as a box-ticking exercise.

Here are some possible business functions that might be theoretically responsible for documentation:

• Customer support
• Technical Support
• Product Team
• Engineering
• Marketing and Communications
• Branding
• Customer Engagement
• Customer Success
• Customer Happiness

How you view your documentation depends on which team you place your technical writers into. Many technical writers view themselves as User Advocates who are bridges between different parts of the business.

Historically, documentation has been viewed as a cost-center, but many companies are turning on to the idea of documentation as adding value and increasing profits.

19. Documentation and marketing

Sometimes it feels like there is an ongoing battle between documentation and marketing – as though these disciplines are somehow opposed. The reality is there would be no point in having documentation for a product that wasn’t marketed. No one would use it.

Marketing is seen as a business function that attracts prospects and customers, but documentation also plays a key role in marketing. Especially in developer docs, product documentation is one of the first things your prospect will look for.

Alternatively, if your knowledge base covers an accessible topic like ‘email marketing’ (MailChimp) or ‘content management’ (Hubspot), then organic traffic from search engines could form a substantial segment of your prospective customers.

Make sure to index your knowledge base and optimize it for SEO.

20. Customer feedback

It’s crucial to collect as much customer feedback as possible for your documentation – without placing too much of a burden on your users.

If they’re already frustrated with a problem they’re having and feel they’ve wasted time, they probably won’t take kindly to a follow-up survey.

Feedback metrics can be as simple as a ratings widget on your documentation – a thumbs up or down, number of stars out of five, or “This page was useful: yes or no?”

The comments on your knowledge base can also be an insight into the mindset of your customers using your docs.

21. Knowledge base metrics

It’s a no-brainer that you should be collecting anonymous data from your knowledge base platform. Most software solutions will provide basic analytics or you can link your knowledge base with your Google Analytics account.

Metrics you can measure are:

• Number of views vs submitted cases
• Bounce rate vs average time spent on page
• New vs returning customers
• Product users vs support requests

You can also start measuring Customer Satisfaction Score and see if your knowledge base content moves the needle on the result.

By setting measurable targets, you can work out if your knowledge base is providing enough ROI.

Final remarks

User documentation is a really exciting area of your business. It’s an opportunity to make your customers happier and stand out from the crowd.

It’s not enough to create a knowledge base and send it out into the world. Continually iterate and improve to stay ahead of the curve.

Inspired to create a knowledge base armed with everything you’ve learned here? Take our knowledge base software KnowledgeOwl for a free spin now.