WRITING

Software User Manual

Dr. G. Venkatraman
 Software User Manual
• Software User Manual Writing - vital and
important part of successful software
development and software engineering.
• Comprises detailed language, illustrations and
photos that help different people understand the
software
• An essential reference material.
• Creating a comprehensively helpful and easy to
read software documentation is challenging
 Software User Manual…

• Sometimes written from the point of view of a

developer rather than a user.
• filled with jargon, acronyms, and directions.
• Making assumptions about the reader's skill
level is incorrect.
• Learn the basic writing skill before venturing
to write a user manual.
 Software User Manual…

• a deep understanding of the inner workings of the

software.
• an understanding of who the end user will be,
what his educational level is, and how that end
user will be using the software.
• the end users do not need the finer points of
programming and the back-end workings of the
software.
• End-user just need to know how to use it to
make their jobs easier.
 Software User Manual…
• The user manual - task-oriented, rather than heavily
descriptive.
• written to help users understand how to execute specific
tasks.
• writer needs to have an understanding of those tasks.
• Going through each discrete step of each feature is
absolutely essential.
• It's not necessary for the writer to necessarily know how the
program was created from a design or development
viewpoint, but it is essential to have a strong working
knowledge of all its features.
• While executing each task, take time to write down each
and every step, including clicks, drop-down menus, and
other actions.
 Software User Manual…
• Developer may not be writing the manual; will be
a valuable resource to the writer.
• plan a kickoff meeting between the writer,
developer and engineers, and potential end-users
• Record the interviews with subject matter
experts and engineers; keep transcripts for later
reference.
 Images
• A user manual should not be too text-heavy.
• Incorporate graphics and screen clips.
• Description of an action is much clearer with
text-based directions accompanied by a screen
clip that clearly illustrates that direction.
• A simple screen capture utility such as the
‘Snipping Tool’ included in Microsoft Windows
works well for capturing these images.
• number each image, and include a caption that
briefly describes it.
• Center it immediately below the paragraph that
first introduces the concept depicted in the image.
 Points to note
• Communicating clearly in a technical document
requires planning and careful adherence to
standards throughout the guide.
• Standards in both in presentation, language, and
nomenclature help avoid confusion.
• Templates are available and can be a good starting
point for uniformity, although these can certainly
be adapted to fit each situation.
• Using a one-inch margin with a single column
best suits the need to add graphics; a two-column
setting might appear too crowded, and can make
placement of images confusing.
 Versioning and Tracking
• a software user guide is likely to go through
multiple iterations
• a review process by multiple stakeholders.
• Creating multiple versions after each review
cycle, each with a different file name, also
helps the process along and makes sure all
stakeholders are satisfied with the final result.
 Types of Documentation
• It can be a user manual that consumers read
to understand the requirements and
operations of a software system so they can
then download it, install it and use it.
• Sometimes more technical, describing the
capabilities and characteristics of the system
for a technical user, such as someone in IT or a
systems administrator.
 Types of Documentation…

• Documentation is designed to inform the reader

about the software and describe how it was created,
what it is intended to do and how it works.
• It should also be easy to find or access, and it
should have the ability to be updated as changes are
made to the software over the course of time.
• the goal for all computer software documentation:
written in language that’s easily understood.
• This can be a challenge when using technical
language.
 Further Categories:
Process documentation
Process documentation is designed for those working in the
internet technology field, and it uses industry-specific
jargon about the process of engineering and developing the
software.
Product documentation describes the product and how it is
to be used.
Product documentation
Product documentation includes both system
documentation, which is technical, and user
documentation, which should not be too technical.
This is because it’s designed for the everyday average
computer user, not someone in the software engineering or
IT field.
 System Documentation and User Documentation

System documentation
• system documentation is much more technical.
• It is geared toward an advanced or specialized reader,
such as a systems administrator or IT professional.
• System documentation includes things like source
code, testing documentation and API documentation
(programmers’ documentation or instructions).
• It describes the requirements and capabilities of the
software and informs the reader about what the
software can and can’t do – in other words, its
functionality.
 User Documentation
• designed for the average user, also called an “end user.”
• written in descriptive language and designed to speak to
the average user of the software or system as opposed to
an IT professional or other technical professional.
• explains to the average person how to properly install and
use the software or service.
• may also include best practices for optimal results,
describe features and the benefits of those features and
can include a description of different tips and tricks for
maximizing software performance
• as well as how to customize the software so it works best
for each user and the intended task.
• Software user manual falls under User Documentation
category.
 Software documentation
• includes an explanation of the purpose of different
settings and how to manipulate them, menus and
other customization options within the software once
it has been installed.
• Software documentation – language of average person
• system documentation - technical standpoint.
• This can be a challenge for a technical professional.
• Understanding the difference between writing for an
end user and writing for another IT professional can be
difficult.
 Components of
User Documentation/Software Manual
• includes everything from how to download and install
software to how to use each aspect of the software or
system.
• This includes user manuals and frequently asked questions
sections, which are designed for everyday consumers to
read, use and understand.
• It can include instructions such as video tutorials, flash
cards, web pages to visit for help or on-screen help text
along with step-by-step illustrations or screenshots on how
to perform all the different functions of the software.
• should also include instructions for troubleshooting
problems that crop up when using the software, such as
how to deal with different errors and how to obtain help if
there is an undocumented problem or an issue they are
unable to solve.
 Documentation and Software Development

• Producing a reliable, understandable documentation is an

important part of software engineering.
• Documentation improves quality and records requirements
and key decisions that went into the creation of the
product.
• Comprehensive and instructive documentation is almost as
important as creating the software itself. It can be tedious
or complicated.
• Software requirements explanations can become several
pages long and extremely technical and text heavy, making
them cumbersome to read through and difficult to use
rather than being helpful and explanatory.
 Table of Contents
of a Software Operation Manual

[The table will help you understand the structure of

a software user manual]
You may refer the website for the full manual:
https://www.plus-vision.com/en/support/download/manual/m-12_software%
20manual.pdf
Introduction
What is Copyboard Soft PLUS TOOLBOX?
Operating Environment
Copyright and License
Connection to the Computer
Description of the included CD-ROM’s menu screen (M-12 setup launcher)
Installation of the Software
Check Prior to Installation
Installation of the PLUS TOOLBOX
Uninstallation of the PLUS TOOLBOX
Menu Screen Names and Functions
Operating the copyboard from the computer
Hardware Setup
Creation and Editing of Headers/Footers
Names and Functions of the Screen Parts
Creating a New Header/Footer
Updating the Internal Header/Footer Information of the Copyboard
Update the Copyboard’s Internal Program
About the security settings
Introduction section in the software

The “PLUS TOOLBOX” software is an application for

connecting the copyboard directly to a computer by
USB port to allow transfer of the scanned data to the
computer using a TWAIN driver so that the data can be
stored on the computer as image files. It can also be
used to manage the copyboard’s operating environment
and security settings from the computer.
Thus as you may understand, a software user manual is
written by computer professionals to help the end-user
of the software. It is equally challenging like software
development. The principles of writing you learnt
elsewhere in the course will help you to write a
software user manual well.
 Recapitulation
• Software user manual falls under ‘User
Documentation’ category.
• Detailed language, illustrations and photos
• A comprehensively helpful and easy to read
software documentation
• A demanding task.