Unit one: Technical and User Documentation

This unit is developed to provide you the necessary information regarding the following content
coverage and topics:
 Technical and User Documentation Review
 Technical and User Documentation Accuracy
 Document inaccuracies

This unit will also assist you to attain the learning outcomes stated above. Specifically, upon
completion of this learning guide, you will be able to:
 Review current version of technical and user documentation based on the latest
operational procedures
 Compare the accuracy of technical and user documentation with current system
functionality
 Identify and document inaccuracies for future reference
 1.1. Technical and User Documentation Review
Documentation may refer to the process of providing evidence ("to document something") or to
the communicable material used to provide such documentation (i.e. a document).

1.1.1. User documentation

User documentation, also known as end-user documentation, is any form of documentation
intended for the end-user of a product or a service. The purpose of this documentation is to guide
the users on how to properly install, use, and/or troubleshoot a product.

We’ve all read some form of user documentation at some point in our lives. They usually come
with products in the form of user manuals/guides that have a bit of a learning curve, such as
gadgets, software applications, and appliances, among other things.

Without this documentation, an average user might not get the full value out of the product. This,
in turn, could result in unhappy customers and high customer care costs and churn rates.

User documentation comes in all shapes and sizes. It doesn’t necessarily have to be in physical,
paper form. It can also be a PDF file, an info graphic, or even a collection of web pages with
helpful resources. User documentation is anything that prevents the end-user from directly
reaching out to your customer service department regarding any confusion about your product.

The main goal of user documentation is to assist the end-users by providing them with clear and
comprehensible info about the particular product or service.

1. Types of User Documentation

As mentioned earlier, user documentation comes in various shapes and forms .However; there is
a simple way to categorize them on the basis of the problems they solve. Keeping that angle in
mind, user documentation can be classified into the following types:

 Installation/Setup Guide
Getting started with certain products, like enterprise software applications, gadgets, fixtures, etc.,
requires some level of technical expertise.

To that end, manufacturers provide such products with comprehensive installation or setup
guides, including detailed, step-by-step instructions to make the overall process user-friendly.
With the help of these tutorials, businesses ensure that the end-users don’t mess up when starting
their journeys with their products.

 Comprehensive User Manual

This refers to the complete, in-depth user guide that comes with any product with even the
slightest learning curve for any product.

It includes everything, from an instruction manual on how to install a product, to troubleshooting

steps, and a breakdown of the user interface and/or the various features in between.

Most of the time, whenever someone talks about user documentation, they’re referring to these
user manuals.

 Reference Guides
Another common type of user documentation is reference guides.

These user documents come with software products, and are intended for more experienced end-
users.
A reference document sheds light on the functionality of any one aspect or feature of a product.
That way, if any user, who already knows a great deal about the product at hand, can get quick
information about certain features without having to skim through the entire user manual.

There are a lot of elements that makes user documentation great. This includes:
 Simple Language
When it comes to any form of technical writing, perhaps the most important thing is the
simplicity of language.
This is especially true for documentation targeted at end-users, who don’t have much technical
knowledge.
 A Good Flow
The second most crucial element of all successful user documentation is having a logical flow or
outline.

The goal is to deliver a coherent experience to your users in a way that makes sense, by solving
one problem at a time.

For instance, if you’re selling enterprise software, you wouldn’t want to start with the advanced
features right off the bat.
Instead, you’d want to start off by helping them get set up, break down the user interface, and
then take them through the individual features and what they can accomplish with them.

 Use of Visuals
The best user documentation has visuals. Visuals can help simplify a complicated process and
make it easier to understand. To that end, in addition to written instructions of a process, it’s
highly recommended that you also show the users how it’s down.

Examples of visuals can include illustrations, screenshots, GIFs, or even short tutorial videos.
 Accessibility
All the digital documentation should be accessible to everyone. This includes optimizing your
content in a way that it shows up properly on both desktop and mobile devices, and can be
communicated to users who are blind or deaf.

For example, if you have your user documentation on a website, you might want to include an
option that allows visually-impaired users to listen to the instructions.

Similarly, for those with audio impairment, ensure that the written content is clearly visible.
 More Resources
User documentation should include additional resources that the user might find useful.

2. Benefits of Effective User Documentation

 Simplifies Product Setup
Software implementation is challenging, especially enterprise-level systems that include
advanced features and a variety of use cases. User documentation guides users through every
step along the way, from signup and user on boarding to continuous training and development
content even after a user becomes proficient with your product.
 Improves Product Proficiency and Adoption
User do cumentation, including customer onboarding guides, how-
tos, and tutorials all teach your users to become expert users of your product and meet their
goals. The more proficient users become in your product, the more likely they are to use it on a
regular basis and continue to be buyers of your platform.
  Fulfills User Demand for Self-Help
Most users prefer using web-based customer self-service support tools over any other forms of
customer support. Good user documentation helps you meet these customer expectations. You
can embed or host your user documentation in places that users can access it without needing to
submit a support ticket, including in your live chat, FAQ page, knowledge base, and directly in
your app itself.
 Reduces Burden on Your Support Team
Thorough user documentation reduces the need for customers to reach out to your customer
support for every little query. Reduced customer support tickets takes the pressure off your
customer service team, allowing them to offer faster service with a more detailed approach to
those tickets that require extra attention. This empowers organizations to take their user support
satisfaction to new levels.

1.1.2. Technical documentation

Technical documentation is any piece of writing that describes the application, purpose, creation
or architecture of a product or service. Its goal is to explain something that an organization
offers. There are several types of technical documents, each intended for a certain audience.
Writing technical documents is usually the responsibility of technical writers, project managers
and members of a development team or experts on the product or service in question.
Effectively written documents help the intended audience by educating them on details that are
necessary, such as for the operation of a product or the understanding of a topic. Examples of
technical documents include:

 User instructions
 Operating instructions
 Servicing instructions
 Installation manuals
 Software manual
 Presentation
 Broachers
 Memos
 Report
 A. Audience for technical documentation
The specific audience of technical documentation depends on the type of document. Many
technical documents accompany products and are intended for end-users. A computer, for
instance, may come with a small booklet written in multiple languages that provides directions
for first use, suggestions for maintenance and warnings against activities that could damage the
product.

Other types of documents are for internal audiences, such as senior stakeholders and
development teams, or for clients. The purpose of internal or client-minded documentation is to
inform others of the technical aspects of a product or its development process. Such documents
are useful for keeping members current on details necessary for decision-making or other
professional tasks.

B. Types of technical documentation

These are the main categories of technical documentation.

 Process

Process documentation describes the development of a product. The audience for this type of
documentation comprises internal members and clients. There's usually some documentation
describing every stage of the development life cycle. For example, at the beginning of a project,
there are project proposals and then plans that include timelines, milestones and data about the
budget. Later, the project manager might submit progress reports or documents detailing step-by-
step procedures

 User

User documents, which are also called product-based documents, relate to products in their
finished state. The audience for user documents is usually the end-user. The documents may
explain how to install, start-up, troubleshoot or repair a product. Alternatively, they may describe
the various features and how to use them or answer frequently asked questions. Companies often
package such documents with the product but also provide them online, so they're accessible
through the customer support page.
Other user documents are for a different type of user, particularly for professionals in the same
field as those who developed the product. For example, software developers may release
technical documentation about the source code of an application. The documents are useful for
transferring knowledge to others, who can then work on improving or modifying the product.

C. Importance of technical documentation

Technical documentation is important because it provides essential information about a product

or service to a person or organization that needs it. This information allows all parties to achieve
their goals. For end-users, the goal might be to enjoy a product while optimizing its functionality
and maximizing its life span, which well-written technical documentation allows them to do.
Meanwhile, the company may save money on customer service and replacements if end users
follow the documentation use the products correctly and refer to the user guide to troubleshoot
their own problems.

Internally, technical documentation can increase productivity and efficiency. For example, in
product development, a technical document might explain how to carry out a procedure. If the
document is clear and easy to follow, it helps to ensure accurate adherence to the steps with no
time wasted. Then, as developments progresses, the documentation can help align the goals and
understanding of the various teams involved.

D. Best practices for writing technical documentation

Effective technical documentation not only provides you with essential information but is also
easy to understand and follow. To create technical documentation that's helpful to your audience,
consider these tips and best practices:

 Have a plan

In technical documentation, a plan is an outline that addresses the task ahead, helping to ensure
that you don't leave out anything important. Before you begin writing, understand and record all
the components you should or might include in the documentation.
  Have a consistent style

Consistency refers to maintaining a unified look and tone, which helps readers to focus on the
content with the distractions of shifting appearance or style. Aim to use the same or similar
layouts, formats, throughout a document or across multiple documents. The idea is to clarify that
your documentation is an extension of your organization's brand.

 Understand your audience

Understanding who your audience is can help you determine not only what kind of technical
documentation to write but also how to write it. For example, if you're writing software
documentation for end-users who are computer programmers, you can expect to write a user
guide that includes advanced industry terminology. In contrast, if your audience comprises
stakeholders of a project who may not be familiar with the concepts of the work, you might be
writing proposals, outlines or progress reports that feature general, easy-to-understand
terminology.

 Be as concise as possible

Being concise helps with understanding by introducing the main point immediately and
removing unnecessary language. Achieve concision through careful proofreading and editing.
Read through your documents to determine which words or phrases may be affecting the clarity.
Remove or rephrase excess or ambiguous passages. Be careful not to remove too much, as this
can cause confusion by providing too little information.

 Optimize for different platforms and devices

Users may access online documentation on various platforms. To maximize accessibility to

users, make sure to optimize your documentation for each. Test the accessibility on different web
browsers, computers and mobile devices to ensure that it appears as it should and remains easy to
view.

1.1.3. Review current version of technical and user documentation

Documentation Review used for

 Overall improvement

 Accurate and up-to-date documents

  Increases credibility

Review Objectives
 Evaluate the documented information
o Accuracy = Correctness
o Completeness = wholeness
o Conciseness = shortness
 Reduce the defect percentage
 Improve the quality of documents
 Focus on correcting the defects
The Need
 Technically correct document
 Concise Information
 Avoid Chaos/disorder
 Timely Delivery
 Satisfaction
1.1.4. Types of document reviews
 Peer Review
o Review by people who have coordinated knowledge and skills.
o Provide a list of exactly what you need them to review
o Assess peer review practice
o Prepare procedure documents
o Formulate a program agenda
 Presentation Review
 Review amongst the technical writers
 Subject matter expert review
 Review for technical information
 Overall Review
 Review by the testing team for detecting defects.
The Review Process
 Plan the review process
 Develop a clear, focused charge for each reviewer to identify important issues and invite
suggestions for improvement.
 Prepare and maintain a review record.
 Make recommended changes to document and respond to the reviewer’s comments.

Difference between Technical and user documentation

Some may argue that there aren’t any differences between the two, and that the only point of
difference is that user documentation comes under the broad umbrella of technical
documentation. The differences are:
 Technical documentation is a broader term than user documentation.

 Technical documentation can be internal and external, while user documentation is

always created for end-user.

 The process of creating user documentation requires a minimum technical background

compared with technical documentation.

 User documentation is meant for the end-user, whereas technical documentation is meant

for everyone else.

Take a software product as an example. Its technical documentation could include the following:

Requirements Documentation – sheds light on what is required from the product, including the
basic and advanced features, functionality, resources, and goals, among other things. This is
meant for the software development teams and testers.

Architecture/Design Documentation – these sketch out the overall design of the software
product and describe the design principles for the development teams.

Process Documentation – these break down the product journey in properly structured formats
for the product team.

Market Strategy – this is created by the product marketing team to provide a north-star and a
game plan to bring a new product to the market.
All of the aforementioned types of documentation have one thing in common – none of them are
meant for the end-user.

1.2. Technical and User documentation accuracy

In order for the documentation to be considered accurate and effective, it must be following the
indicated format for the type of document that it is considered. Along with the proper formatting
techniques, the appropriate media must be maintained for the documentation in question.

Documentation is created to find a solution for any problematic situation competently and
without panic. This is a fundamental principle when thinking over the content and structure of
any technical document. Here is the list of qualities to pay attention to when testing the the
accuracy of the documentation:

 Ease of understanding. If a product is designed for ordinary users, then the

documentation for it should describe the user's actions in simple, understandable terms.

 Grammar. Sure enough, the content must be composed correctly.

 Scenarios efficiency. The scenarios should be described accurately; their execution

should lead to achieving the goals for which the product was created. If there are
alternative scenarios, they should also be mentioned.

 Completeness. Describe every function element, whether an interface element such as a

button, checkbox, etc., or the command.

 Correctness. If the user is in a hurry, they need to find the answer to the question or
follow the instructions without additional references or wasting time.

 Structure, easy document navigation. The documentation should have a clear structure,
and the user should be able to find information on the table of contents quickly

 The sequence of actions. In some scenarios, the sequence of steps is important.

 Accuracy of links. Any online document contains links. Check the links to find out if
some of them are broken. With Click Help, you can do it with the Link Viewer feature.
The Click Help engine checks: Cross-topics links inside topic content, resource links in
style files, links in scripts files.
  Relevance. If you test the documentation for a software product with many versions, you
should pay attention to the relevance of the description.

1.3. Document inaccuracies

Document Error means a failure of documentation to accurately describe a program function
contained in the specification for that a program or a failure of documentation to meet the agreed
requirements for that documentation, or a failure of documentation to enable reasonably
competent users to correctly operate.

In order for the documentation to be considered accurate and effective, it must be following the
indicated format for the type of document that it is considered. Along with the proper formatting
techniques, the appropriate media must be maintained for the documentation in question