Difference Between User v End User in Technical Documents?

When should I use ‘user’ instead of ‘end user’ in my user guides?

Let’s start with a definition of end user.

Definition: Where does the phrase ‘end user’ come from?

According to Wikipedia: An end user is a person who uses a product. The term is based in the fields of economics and commerce. A product may be purchased by several intermediaries, who are not users, between the manufacturer and the end user, or be directly purchased by the end user as a consumer. For example the end user of a pharmaceutical product is the patient who takes it, rather than distributors, pharmacists and physicians who may purchase it in their behalf; or the user can buy the product at a drugstore.

Investopedia, which has a financial glossary, sees it as: The true consumer of a product or service. The term “end-user” is used to distinguish the person who will actually work with the good or service from individuals who are involved in other stages of its development, production and distribution.

There are three points to address here:

  • Audience expectations
  • Style guidelines
  • Context of the material

Let’s look at each.

Audience expectations

Every read comes to a document with certain expectations. So, for example, when you open a User Guide, you expect an introduction to put things in context, more of that later, then a set of procedures, and possibly some troubleshooting tips. How do I do such as task.

Because you’ve read so many guides over the years, you, the reader, come to expect certain terms, phrases, layout and structures in the document you’re reading.

Common terminology is one of these.

  • Do your readers expect to see User or End User?
  • Is the phrase User or End User used in your other documents?
  • Is there a specific reason why you prefer User instead of End User?
  • What misunderstandings could occur if you chose one over the other?

Style Guidelines

Most companies use either an internal style or rely on one of the industry standards, such as:

  • Apple Publications Style Guide – editorial guidelines for text in Apple instructional publications, technical documentation, reference information, training programs, and the software user interface.
  • Microsoft Manual of Style for Technical Publications – for technical documentation including use of terminology, conventions, procedure, design treatments, and punctuation and grammar usage.
  • The Cambridge Handbook for Editors
  • Fowler’s Modern English Usage
  • The King’s English
  • The BBC News Style Guide
  • The Economist Style Guide
  • The Guardian Style Guide
  • The Associated Press Stylebook
  • The Chicago Manual of Style
  • The Yahoo! Style Guide
  • The advantage of a style guide is that it gives your documents:

A consistent voice across all materials

Ensure that all writers comply with these agreed words and phrase and

Provides a reference for any questions or disputes between the writers

‘Well, it says in the style guide that we should…’

What this also means is that you, as the author of the user guide, need to decide which term to use –User or End User – and then add this to your own internal style guide.

Internal House Style Guides

This internal style guide doesn’t have to be lengthy. Some I’ve seen are less than five pages. But you need to cover the critical things in it. And one of these is whether you should use User or End User.

Once you’ve agreed on this, and it’s in the guide, then there is no further interpretation.

Follow the style guide!

Context of the Documents

The final point relates to context. This means: what is the reader expecting at this specific moment in time?

In other words, sometimes it may be appropriate to use end user but may be not here. For example, in some companies the phrase end user refers to so-called ‘front line’ workers.

In others, it means users with the LEAST proficiency with your product; beginners and other low level users.

When I started in technical writing, ‘end user’ referred to the user at the very end of the line, i.e. the person using it in the real world, not Administrators, developers, and so on.

Using ‘You’ in User Guides

I also try to balance the tone in the guides by speaking to the reader directly. Instead of referring to this abstract concept – the user – I talk to you, the person reading this page. To me, it feels more natural.

Of course, if you overdo it, it sounds contrived as though I’m trying to be your BFF.

Summary

Personally, I try to avoid end user. There’s something negative about it. It seems to imply that the user isn’t that proficient with the system.

Also, the word ‘end’ has never sounded nice to me. It sounds too dark. While most of us may not mind begin referred to as the user – for a while, anyway – we probably don’t want to be called an end user. Doesn’t sound like a compliment, does it?

Indexing Guidelines for Use Guides Part 1

Should you add an index to your user guide and if so what should you include? Both are worth considering if your user guide is more than twenty pages. Why twenty?

In general, if a document is relatively small, there is no need to include an index. And while there are exceptions, you can usually reserve indexes for larger documents. The questions then are:

  • What to index?
  • What level of information needs to be indexed?
  • What can be omitted?
  • How to index?

Put yourself in the user’s shoes. Why do they go to the index? It’s usually because they can’t find the information in the table of contents and don’t have time to scan the entire document. Also the same item may be in different places in the document.

Suggested terms to include are as follows:

  • Product names
  • Specifications
  • User Interface controls
  • Techniques to perform tasks
  • Materials
  • Conditions

Create a reference list

Read the document and as you can come across key words or terms relating to the subject matter, add these to the list. Later, you can decide what goes in or out. Notepad is a simple way to track these.

What level of information needs to be indexed?

As you record these words, note variations of the term, for example, if your document is about investing the terms CDS and Credit Default Swap may both need to be indexed.

Why?

Users search in different ways.

Some will type in CDS, others Credit Default Swap. Add both to the index and cross-reference the related keyword. Make sure to include possible synonyms or variations for each term. Note the page number where the terms occurs, and the context in which it is used.

Next, identify what information can be indexed and what should be excluded.

What can be omitted from the index?

After you have created your Reference List, you’ll get a feel for terms that come up repeatedly whereas others may only be referenced once and may not be index candidates.

In addition to this, the following can usually be excluded from the index:

  • Footnotes
  • Endnotes
  • Abstracts
  • Tables
  • Images
  • Appendices

Note: ignore words that are mentioned in passing and are not directly related to the core functionality.

What should be indexed?

  • Focus on those critical words (and phrases) that help the reader understand the subject matter.
  • Next, look at the verbs used in conjunction with these terms, for example, printing, deleting, merging etc that users are most likely to need. Develop your index around these words and phrase.
  • Words also known as

If necessary, include similar words that may also be used by reader, for example:

Web Content

Also known as: “E-Content”, “Online Content”, “Internet Content” and “Digital Content”

Index to Page Ratio?

If I have a 100 page document, how long should the index be?

Something to consider is that for every 100 pages, you should have about 5 pages of index entries. That means that 5% gets indexed. I’ve heard other indexers use a higher percentage.

It’s up to you. However, if you deliver less than this, maybe your index is too shallow.

Index cards photo courtesy of lisa eckstein

Difference Between User Guide and Getting Started Guides

In this tutorial we look at the difference between User Guide and Getting Started Guides? When should you create one instead of the other? What goes into the User Guide that doesn’t go into the Getting Started Guide and the other way round? Let’s take a look.

User Guides: what to include?

  • Are comprehensive. They cover all aspects of the application.
  • They may also be written for different levels of users, starting with beginners and working your way up to more advanced, power users.

Getting Started Guides

  • …tend to be for beginners.
  • It’s really to get you up and running. Once you see how it works, and have played with the product, you can consult the user guide for more advanced procedures and troubleshooting tips. Troubleshooting tips are rarely included in the getting started guides.
  • Are meant to be used as a reference document. If you need to know something very specific, it should be covered in the user guide. For this reason, you will also include a glossary, definitions, screenshots, and an index.

Getting Started Guides

Describe the critical information you need to get started with the application, for example, online banking or using your new digital TV. However, they don’t go into specific details that will be covered in the user guide.

Are short, often meant to be printed out, and may include photos or screenshots to orient the reader.

Do I need both?

It depends on your:

  • Documentation Plan – is there enough time and resources in your Documentation Plan to do this? In others words, can you justify that both documents MUST be delivered? Which is the most important? Can you schedule one before the other? Do both need to be delivered as PDFs or can you put them both Online? Usually, the getting started guides are short documents, often printed out and the user guide is available as online help. There are exceptions of course.
  • Budget – is there sufficient monies available to do this? Every page you write costs money. Do you have the budget to write a 10 page Getting Started guide or should you enhance the online help instead?
  • Resources – who will write the Getting Started Guide? Do they have the skills to do this? If not, get them to review getting started guides from other companies, study what works, create a template, and prepare a draft. If you’re pleased with this, encourage the technical writer to create a formal draft and review this against best practises.
  • Justification – who requested the Getting Started Guide? Is there a strong justification to do this or is it a pet project that one of your team wants to write? Either way, is this a good use of their time or should they be working on something more important?
  • Customers – why have customers requested this? Before you start your Getting Started Guide, look at the reasons why customers have requested this and develop your guide with these factors in mind. For example, some customers prefer to SEE how to assemble a computer, TV, or other item. Maybe your User Guide doesn’t include sufficient photos, images, or screenshots. Look at how your competitors approach this and develop your Getting Started Guide with this in mind.

Example Getting Started Guides

Note that the MineCraft Getting Started Guide is referred to as a Beginners Guide and that makes sense. That’s the point. It’s there to get you up and running. Once you understand how it works, and begin to use it, you’ll probably run into a few areas where you need clarification. Or maybe things simply don’t work.

That’s why you need the User Guide. This provide the more granular How do I type information  that’s not covered by the scope of the other document.

Which do I write first?

Write the user guide first, then distil the critical tasks into a short, for example, four page, document. You may need to reword some sections, but you should understand what goes into the getting started guide AFTER writing the user guide, something you may not know at the start.

Photo: library_of_congress

User Guides: How to describe System Crashes

When writing user guides you may need to describe how to application stopped working. The most common way to write this is to say that it crashed but it’s best to avoid this as it’s misleading, sometimes inaccurate, and sounds like jargon.

So, what’s the best way to say that your application crashed without using this phrase?

Should you even write that your software ‘crashed’ or is there a more elegant way to do this? For example, instead of using the rather crude phrase ‘crashed’, you can suggest that the application:

  1. Stopped responding
  2. Failed to respond
  3. Ceased to function
  4. A flaw, failure, or fault was encountered.
  5. An incorrect result was displayed
  6. An unexpected result occurred

In many cases, this is more accurate as your system may still running (at least on some level) but was unable to respond, for example, if that network went down or a third party application also failed to respond.

Isn’t this shifting the blame?

It could read like that but remember in some cases, your software may not be the culprit. The reason the product stopped working may be due to something beyond your control. Also, using phrases such as ‘crash’ undermines the integrity of your documentation. It’s too casual. It also sounds like jargon.

The reader probably senses that you should use a more exact, accurate, even if they can’t articulate this.

Using more elegant phrases, such as failed to respond, softens the blow and prepares the reader for how to resolve the issue. In other words, how to fix the application so it starts responding.

Apple Style Guide on describing computer crashes

Provides the following guidelines for describing crashes:

Don’t use; use quits unexpectedly, doesn’t respond, or stops responding. If you must use this word, put it in quotation marks and reassure the reader that the term crash doesn’t imply damage to hardware or software.

Microsoft Style Guide for Technical Publications

Encourages you to avoid using the term as its jargon. Instead, it suggests:

Use fail for disks or stop responding for programs and operating systems. Avoid whenever possible.

The IBM Style Guide also suggests you use a more specific term, such as fail.

One final point is to be consistent. Use the same phrase across all documentation.

If possible, work with developers to change any error messages that refer to crashes so they use the same phrasing. This helps create a consistent tone and voice across all technical documents.

How to write your first user guide

When’s the last your read a user guide and thought, “Wow, that’s great!” User guides have a bad reputation. Instead of seeing them as something that helps get the job done, many feel that user guides (aka user manuals) makes things more different.

So, how can we write a user guide that:

  • Users want to read.
  • Want to share with others.
  • Helps reduce the cost of technical support.
  • Increases your credibility as a quality provider.
  • Is a pleasure for you to write?

How to structure your User Guide

There’s a saying in sports – fail to prepare; prepare to fail. And the same applies when writing user guides. Before you write a single word, outline the key sections of the guide and then start on each section.

Most novice writers make the mistake of getting pumped full of energy and then ‘going for it’. That’s fine if you want to get something out to customers but, in your enthusiasm, you will probably overlook some of the problems they’re having with the applications.

Let’s step back a moment and look at some the guidelines you need to cover in your document:

  • How to use a style guide for your user guide
  • How to identify the users problems
  • How to format the user guide correctly
  • How to create the table of contents
  • How to use images effectively
  • How to make information easy to find
  • How to write instructions
  • How to publish the manual to pdf, online help and mobile devices
  • How to test the user guide
  • How to update the guide after getting feedback

How to use a style guide for your user guide

Before you start writing your user guide, select one of the industry standard style guides, such as the Microsoft Style Guide for Technical Publications. Then stick to it.

  • No style guide is perfect. But, training yourself – and other writers – to use the style guide will contribute to the quality of your documents.
  • It also takes personal opinion out of the picture and reduces squabbling between writers.
  • When in doubt, consult the style guide.
  • Identify the most frequently used sections in the style guide, for example, how to use bullet lists or write instructions, and print these out.

How to identify the users problems

One way to look at user guides is to think of them as How Do I Manuals.

How I do… solve this problem, find this feature, change the options. Write your user guide with this in mind and your readers will thank you.

How do you identify users problems?

  • Look at technical support queries from customers. What problems do they have most frequently?
  • Ask questions on forums, social media networks, and other areas where you can get feedback.
  • Ask open ended questions, such as, ‘What’s the one thing about our product that gives you the most problems?’ Then explain how to do this in the User Guide.
  • Use the application yourself and identify the tasks you need to complete to use it effectively.

Once you have done this, create a master list of questions (i.e. problems) that the user needs to understand. This is the foundation of your user guide.

How to create the table of contents

There are several ways to create the table of contents for user guides. One consideration is which target readership you’re writing for. In other words, are you writing for:

  • Beginners
  • Advanced users
  • Power users

Here’s the problem:

If you write for beginners, where do you put the material for the more advanced users? One way to do this is to create a standard ‘hold all’ table of contents at the start of the document… and then add a power users section at the end.

Remember, most users don’t read the manual from start to finish. Instead, they look for what they’re trying to fix, locate it, and then read that page only.

With that said, you still need to create a table of contents. Here’s one approach.

  • Identify the high level activities involved in using the application, for instance, setting up, getting started, using features, and configuring the software.
  • Use these to create the main chapters in the document.
  • Then, drill down and outline the main tasks for each chapter. In Getting Started, identify the tasks they need to complete to get the software up and running.

Numbering Conventions

Create a consistent naming convention for all sections. For instance, use 1.1, 1.1.1 and 1.1.1.1.

To be honest, I rarely go down to 1.1.1.1 as it creates problems with MS Word and also makes it hard for the reader to find information when searching online documents or using the index. Stick to levels 1.1 and 1.1.1 if possible.

How to use images effectively

Let’s look at the role of screenshots in user guides. One of the mistakes novice technical writers make – or those who are new to writing user guides – is to include screenshots on as many pages as possible.

Here’s a better approach when adding images to user manuals:

  • Add screenshots that SHOW a procedure that may otherwise confuse the reader. A good example is where they are ‘floating windows’ and it may be hard for the user to tell which window to click on.
  • Add screenshots that provide granular details, for example, if an option is hidden or hard to find in the user interface.
  • Add screenshots the show the correct option, for example, in a drop down menu. Without the screenshot the user may not see this option.

What you shouldn’t do is add screenshots that:

  • Increase the page count.
  • Clutter up the document.
  • Make other information harder to find.
  • Frustrate the user who keeps getting distracted by this eye candy.

To make sure you – and your team – use screenshots correctly:

  • Establish guidelines for taking screenshots.
  • Don’t capture the entire desktop unless you need to.
  • Focus on what action the user needs to complete.
  • Crop the screenshot and remove any noise that may distract them.
  • Add the image to the user guide next to the correct text.
  • Include a caption.

How to format the user guide correctly

The next step is to format the user guide. What this means is that your final draft will:

  • Have the same look and feel.
  • Use the same fonts across all sections.
  • Have the same size/design for screenshots.
  • Use the same color schemes.
  • Have the same page size. This can change if you copy/paste large text blocks from other documents.

In addition to the ‘cosmetic’ side of the user guide, i.e. how it looks, you need to format the document on other levels. Check that it:

  • Uses the same version of English, e.g. UK v US English.
  • Uses the same numbering system.
  • Has consistent headers and footers.
  • Follows a logical order in the table of contents.

How to make information easy to find

Your document is there to help users solve problems. One way to do this is to help readers find the answers to their questions fast.

While finding these answers may seem obvious to you – after all, you’ve lived with the document for weeks – for others finding this information may not be so easy.

For instance, if they can’t find it in the table of contents, then where should they go?

You can make information easy to find as follows:

  • Add keywords to the section headings. Keywords are words users are likely to use when searching for answers
  • Remove filler or obscure words from your headings, section titles and table of contents
  • Create an index. Add the critical terms here.

NB: Remove terms that clog up the index. While valid in their own way, they make it hard to user to find the more critical terms.

You can further refine the user guide as follows:

  • Create a one page cheat sheet. Answer the most frequently asked questions here.
  • Organize the information in a hierarchy. Think of a pyramid with the most important tasks at the top.
  • Divide the document into sections by frequency of use.
  • Divide the document into sections by level of expertise.
  • Use colors, shading, underlines etc to highlight importance.
  • Create a list of keywords and use these to build your index.
  • Add synonyms to the index. For example, in the US it’s called an elevator. In Europe, it’s a lift.
  • Include a glossary of terms.
  • Include a trouble-shooting section and a list of frequently asked questions.

How to write instructions

The difference between writing user guides and other type of documents is this. When writing a user guide, think in terms of ‘How Do I…’

  • How do I install the software?
  • How do I find the option to change channels?
  • How do I change security settings?

And then answer these questions.

If you write your user guides from this angle – and avoid filling out the document just to increase the page count – your readers will find your document more useful and rely on it for their answers.

One practical way to do this is to learn to write instructions:

  • Identify the problem.
  • Describe the pre-requisites that may need to perform.
  • Give step by step instructions on how to solve the problem.
  • Include notes, warnings or alerts where necessary.

When writing the instructions, follow these guidelines:

  • Use the ‘you’ convention when writing.
  • Write the sequences in the correct order.
  • Write in the present tense. Users are using your application right now!
  • Write in the active voice. Be clear about who does what.
  • Keep sentences short. Avoid waffle.
  • Number the steps (e.g. Step 1, Step 2 etc.)
  • Describe the purpose and meaning of symbols, icons and codes at the start of the documents.

Mistakes to avoid when writing instructions:

  • Don’t say ‘one should’ or other dated writing styles. Write in everyday language.
  • Don’t write long paragraphs.
  • Don’t use jargon, cliches or industry terms. Also called TLAs. Three Letter Acronyms
  • Don’t patronize the user.
  • Don’t assume the user has prior experience or knowledge of how your product works. Give them some background information and point them to knowledge bases if necessary.

How to publish the user manual

Once you’ve completed the user guide, you need to publish it in a format that suits the reader.

In general, this means converting the user guide to:

  • PDF
  • Online Help
  • Formats for mobile devices

Be careful when converting your documents to these formats as each one has its own limitations and issues.

For example…

When converting your user guide to PDF, make sure the:

  • PDF opens at the correct screen size.
  • Includes the correct table of contents.
  • Has a consistent look and feel, especially regarding page size and layout.
  • Fonts render currently.
  • No error messages appear when you open the PDF on different PCs or web browsers.

When converting your user guide to online help, make sure the:

  • Index is correct and reflects the table of contents.
  • Keywords are added to the index. Negative keywords are removed.
  • Images appear correctly. If you use the ‘wrong’ file formats, they may not appear correctly onscreen.
  • The navigation makes sense to the reader.
  • Search works correctly and gives the right results.

When converting your user guide for mobile devices, make sure the:

  • Pages download quickly.
  • Font size is easy to read.
  • Images appear correctly and don’t align above/below the text.
  • Search option works correctly.
  • Links to other sites are correct.
  • Contact information is correct and works.

How to test the user guide

Before you release your user guide, you need to check that it works, right? Otherwise, you can’t tell if it solves the reader’s problems.

How do you test the user guide?

  • Share the document with a series of test users.
  • Ask them to perform specific tasks.
  • Monitor how they find this information in the user manual.
  • Observe how to follow the instructions to accomplish these tasks.

How to update the guide after getting feedback

After you’ve done this testing, revise the text where necessary.

  • Update the user guide version number to reflect this change.
  • Release the new ‘final’ version.
  • Archive the previous copies.
  • Remove them from share drives, networks and other locations.

Conclusion

Creating a user guide is a wonderful way to help others use your software or service. As it’s most user’s first port of call, it creates a deep impression on how they view your company. So, take your time and make sure the user guide solves their problem as quickly as possible.

While other guides are written for sys admins, developers, and testers, this is specifically for Customers. Instead of calling it a User Guide, see it as a Customer Guide. And you want your customers to be happy, right?

Have a problem writing your user guide? Drop me a line and see if we can help.