How To Write User Manual For Web Application

Posted on by

Supplier Web Application User Guide Tieto Corporation BIX Supplier Web Application Guide v2.0. INN Data Management Integrated System User Manual - 13 - 3. Filling the INN PDF form The INN on-line application uses the Adobe Reader software as user interface. Opening the PDF file, the user will see a PDF document in Figure 15. Figure 15 INN PDF document The yellow fields are the required information (see Figure 16) in order to start the.

What is a User Guide? A User Guide explains how to use a software application in language that a non-technical person can understand. In general, user guides are part of the documentation suite that comes with an application for example, Data Sheets, Release Notes,Installation Guides andSystem Administration Guides.

Technical Writers will often create a Documentation Plan before writing their user guide. This defines the scope, size, delivery format and resources required to produce the actual user guide.

As the name implies, User Guides are written to help people understand an software application or IT system. They are also called User Manuals. When writing a User Guide, use simple language with short sentences. This writing style helps the user understand the application.

Our User Guide templates can be used to create user guides, user manuals, getting started guides and other types of technical documents. A User Guide is an online or printed book that describes how to use a software application.

User Guides are the first port of call when something needs to be read. As many people read user guides when frustrated and after having lost patience with the software, you need to write your material to address their concerns quickly.

User Guides are often written for non-technical individuals. The level of content and terminology differs considerably from, for example, a System Administration Guide, which is more detailed and complex.

This rest of article offers some guidelines to consider when writing your User Guide, such as:

  • Identifying your audience
  • Writing sections
  • Defining style guide and standards
  • Delivery formats

Identifying Your Audience

As with all types of writing, the first step is to define your TARGET AUDIENCE. Your target audience are the people who will user your document. As different readers have different requirements, you need to consider their specific requirements. Use this template to learn more about the target audience for your projects and what they want to achieve, for example, read your user guide, visit your website or buy your product.

The worksheets include 130 points you can use to capture demographic date so that you have a more holistic view of their wishes, desires, fears, and preferences.
  • Identify the target audience
  • Identify their level of technical knowledge
  • Identify how they will use the guide

Audience Definitions

In the planning process, develop an audience definition that identifies:

  • The user
  • The system
  • The tasks

Software is used to do specific things. Users want to know what the software can do for them, for example, how to print a page in landscape.

They are generally not interested in the nitty-gritty technical details; they want to click a button and get a result. The User Guide is to teach them how the software helps them to do something.

Depending on the guide in question, you may need to address several audiences. For example:

  • Programmers who will troubleshoot the program
  • IT Managers who want to know the resources the program requires
  • Project Managers who want to confirm that the original requirements were met.

If you are writing for more than one audience, develop an audience definition for each one. Examine the definitions and see if you can address all audience types with one document. In many situations, you may need to write a number of documents, of which the users guide is only one.

  • When planning, use the audience definition to focus your decisions.
  • When writing, the audience definition serves as a guide for the documentation team and as a benchmark for evaluating the results.

Here are some questions that will help define your audience's needs:

  • Where will they use the document, for example, in the office, at home, in their car?
  • How much experience have they of using your application?
  • Is this guide an upgrade to an existing application?
  • Is your application new? If so, you may want to include a Getting Started document to introduce the software.
  • How will they use the user guide?
  • Will they install the software by themselves or do so over the internet?
  • What level of detail is required?
  • Will graphics help their understanding of how to use your product?

Writing the User Guide

User

Each user guide is comprised of front page, body sections, and a back page. The following section describes what each of these needs to contain.

Front Page (cover pages)

Include a cover page, table of contents, and a preface, if necessary.

Cover and Title Page

If the user guide is copyrighted, include a copyright notice.

Copyright © 2020 The Name Of Your Company.

Place the copyright notice on the cover (and also the title page).

Disclaimer

Include a standard disclaimer inside the front cover that outlines the Terms and Conditions for using this guide.

Preface

Use this section to reference other documents related to the software. Make sure you refer to the correct release number for all software and documents that you refer to. If necessary, include a section on 'How to use this guide' as an introduction.

Contents

You must include a table of contents. the only exception is if your guide is less than ten pages, in which case you should probably refer to it as a Getting Started guide or Reference Guide.

If this user guide is more than twenty pages, include an index at the end of the document.

Body of the guide

This is the heart of the guide. In the main body, separate the procedures (also called instructions) from reference materials. This will help the user navigate their way through the guide much faster.

Procedures

Procedures help the user perform specific tasks. They are also known as instructions or tasks. Examples of these may include:

  • When, why, and how you can perform a task, for example, printing a document, cropping an image, uploading a file.
  • What the screen will show after you perform a task, for example, an updated view of your bank balance.
  • Examples of tasks and program operation.

Writing procedures

Writing procedures involves the following tasks:

  • Identifying the major tasks
  • Separating each major task into subtasks
  • Writing a series of steps that walk the user through each subtask
  • Using an 'if-then' approach when explaining decisions that users can make.

Chunking text

Breaking large pieces of information into smaller piece of information is called 'chunking.'

When writing user guides, you can separate information by menu options and their respective consequences, for example, showing the user the results of each action.

Subtasks that need to be performed can be divided into chunks. Each chunk can form a new chapter or section within the guide.

Use a consistent format for each section, for instance:

  • Introduce each section with an overview of the task to be performed
  • Describe the inputs and outputs. In other words, what the user must enter into the system and what the system will do as a result.
  • Describe the procedures for accomplishing these tasks.

Number your steps

When writing procedures, number each step and use the imperative form of verbs, for example:

Press ENTER

or

Click 'Yes' and press ENTER to submit your details.

Using the If-Then Approach

When users are allowed to make decisions, use an If-Then approach to show the different result for each decision they make.

If you choose 'Yes,' the program will make Firefox your default web browser. If you choose 'No,' it will set Opera as your default browser.

Use diagrams to illustrate more complicated procedures.

Reference Materials

User turn to reference material when they need detailed information on a specific topic, for example, settings or parameters they must enter.

Reference materials can include:

  • Program options, for example, different menus and buttons that are presented to the user
  • Keyboard options, for example, hold AltGr and 4 to show the Euro symbol
  • Error messages that may arise when you use the application

Sample User Manual For Web Application

  • Troubleshooting tips to resolve these issues
  • Frequently asked questions that the user may have about the software

Back Matter

Add a Glossary of Terms and an Index towards the end of the document.

Glossary

The glossary should cover all acronyms and industry terms used in the document. Help the user understand your material. Do not alienate them by using jargon and assuming that they know the meaning on these words.

  • A short glossary can appear at the front before the table of contents
  • A larger glossary should appear in the back matter.

Highlight glossary terms (by italics, for instance) the first time they appear in text.

Index

Any guide longer than 20 pages benefits from an index. An index helps users locate specific items very fast without having to search through the entire document manually. Large documents without an index are impossible to use efficiently.

Establishing Standards

As well as writing the guide, you also need to consider how the document will be delivered, for example, as a book, online or a PDF.

Areas that need consideration include:

  • Format (the design and layout of the pages)
  • Style (elements affecting readability, such as font, size, color)
  • Other requirements that are specific to each delivery format. For example, PDFs may need security settings applied so material cannot be copied; partner logos may need to be added; terms and conditions may need to be updated.

Document Format and Structure

If you are writing a user guide for a client, rather then your own company, check if they use a specific style guide or have a preference for how the document should be presented. Check this with the client during the planning phase.

Use a document map to organize the guide. To do this:

  • Use headings for organizing information.
  • Include page numbers and section titles on every page, either in footers or headers.
  • Consider using dual columns. This lets you put headings in the left-hand column and the text in the right-hand column.

Style

Use an appropriate style. Decide on the technical level of your language, how you address the user, and conventions that are required.

Technical Language

Match the level of technical language with the audience ¯s level of proficiency. Always underestimate the knowledge of your readers rather than overestimate it.

Limit technical terms to those the user will encounter. If you must define a large number of terms, use a glossary to supplement definitions in the text.

Addressing the User

When writing procedures, use the active voice (e.g. Click this) and address users directly (write 'you' rather than 'the user').

When explaining an action, use the 'command' form of the verb:

'Choose an option from the menu and press [ENTER].'

Presenting your material

You can improve the readability of your documents by using specific formats to distinguish different types of information.

For example, you can distinguish the user's input from the system's response by:

  • Indenting text
  • Using columns to layout text
  • Providing illustrations or photographs that highlight key areas
  • Using different fonts and type features (bold, italics and underline)

Nonverbal devices, such as icons or diagrams, help supplement verbal instructions.

Special Requirements

If the guide is to be used outdoors, in a car, or on the move, make sure the font size is large enough to read easily.

Use spiral biding so the book does not to break easily, and high-quality paper so the text does not smudge or leave stains on the reader's hands.

PS - Download the User Guide Templates here

Before we pen down more details on the type of web testing, lets quickly define Web Testing.

What is Web Testing?

Web Testing in simple terms is checking your web application for potential bugs before its made live or before code is moved into the production environment.

During this stage issues such as that of web application security, the functioning of the site, its access to handicapped as well as regular users and its ability to handle traffic is checked.

How to test Web Application

In Software Engineering, the following testing types/technique may be performed depending on your web testing requirements.

1. Functionality Testing:

This is used to check if your product is as per the specifications you intended for it as well as the functional requirements you charted out for it in your developmental documentation. Web based Testing Activities includes:

Test all links in your webpages are working correctly and make sure there are no broken links. Links to be checked will include -

  • Outgoing links
  • Internal links
  • Anchor Links
  • MailTo Links

Test Forms are working as expected. This will include-

  • Scripting checks on the form are working as expected. For example- if a user does not fill a mandatory field in a form an error message is shown.
  • Check default values are being populated
  • Once submitted, the data in the forms is submitted to a live database or is linked to a working email address
  • Forms are optimally formatted for better readability

Test Cookies are working as expected. Cookies are small files used by websites to primarily remember active user sessions so you do not need to log in every time you visit a website. Cookie Testing will include

  • Testing cookies (sessions) are deleted either when cache is cleared or when they reach their expiry.
  • Delete cookies (sessions) and test that login credentials are asked for when you next visit the site.

Test HTML and CSS to ensure that search engines can crawl your site easily. This will include

  • Checking for Syntax Errors
  • Readable Color Schemas
  • Standard Compliance. Ensure standards such W3C, OASIS, IETF, ISO, ECMA, or WS-I are followed.

Test business workflow- This will include

  • Testing your end - to - end workflow/ business scenarios which takes the user through a series of webpages to complete.
  • Test negative scenarios as well, such that when a user executes an unexpected step, appropriate error message or help is shown in your web application.

How To Write A Technical Manual

Tools that can be used: QTP , IBM Rational , Selenium

2. Usability testing:

Usability Testing has now become a vital part of any web based project. It can be carried out by testers like you or a small focus group similar to the target audience of the web application.

Test the site Navigation:

  • Menus, buttons or Links to different pages on your site should be easily visible and consistent on all webpages

Test the Content:

  • Content should be legible with no spelling or grammatical errors.
  • Images if present should contain an 'alt' text

Example User Manual For Web Application

Tools that can be used: Chalkmark, Clicktale, Clixpy and Feedback Army

3.Interface Testing:

Three areas to be tested here are - Application, Web and Database Server

  • Application: Test requests are sent correctly to the Database and output at the client side is displayed correctly. Errors if any must be caught by the application and must be only shown to the administrator and not the end user.
  • Web Server: Test Web server is handling all application requests without any service denial.
  • Database Server: Make sure queries sent to the database give expected results.

Test system response when connection between the three layers (Application, Web and Database) cannot be established and appropriate message is shown to the end user.

Tools that can be used: AlertFox, Ranorex

4. Database Testing:

Database is one critical component of your web application and stress must be laid to test it thoroughly. Testing activities will include-

  • Test if any errors are shown while executing queries
  • Data Integrity is maintained while creating, updating or deleting data in database.
  • Check response time of queries and fine tune them if necessary.
  • Test data retrieved from your database is shown accurately in your web application

Tools that can be used: QTP, Selenium

5. Compatibility testing.

Compatibility tests ensures that your web application displays correctly across different devices. This would include-

Browser Compatibility Test: Same website in different browsers will display differently. You need to test if your web application is being displayed correctly across browsers, JavaScript, AJAX and authentication is working fine. You may also check for Mobile Browser Compatibility.

The rendering of web elements like buttons, text fields etc. changes with change in Operating System. Make sure your website works fine for various combination of Operating systems such as Windows, Linux, Mac and Browsers such as Firefox, Internet Explorer, Safari etc.

Tools that can be used: NetMechanic

6. Performance Testing:

This will ensure your site works under all loads. Software Testing activities will include but not limited to -

  • Website application response times at different connection speeds
  • Load test your web application to determine its behavior under normal and peak loads
  • Stress test your web site to determine its break point when pushed to beyond normal loads at peak time.
  • Test if a crash occurs due to peak load, how does the site recover from such an event
  • Make sure optimization techniques like gzip compression, browser and server side cache enabled to reduce load times

Tools that can be used: Loadrunner, JMeter

7. Security testing:

Security Testing is vital for e-commerce website that store sensitive customer information like credit cards. Testing Activities will include-

  • Test unauthorized access to secure pages should not be permitted
  • Restricted files should not be downloadable without appropriate access
  • Check sessions are automatically killed after prolonged user inactivity
  • On use of SSL certificates, website should re-direct to encrypted SSL pages.

Tools that can be used: Babel Enterprise, BFBTester and CROSS

8. Crowd Testing:

You will select a large number of people (crowd) to execute tests which otherwise would have been executed a select group of people in the company. Crowdsourced testing is an interesting and upcoming concept and helps unravel many a unnoticed defects.

Tools that can be used: People like you and me !!!. And yes , loads of them!

This concludes the tutorial. It includes almost all testing types applicable to your web application.

As a Web-tester its important to note that web testing is quite an arduous process and you are bound to come across many obstacles. One of the major problems you will face is of course deadline pressure. Everything is always needed yesterday! The number of times the code will need changing is also taxing. Make sure you plan your work and know clearly what is expected of you. Its best define all the tasks involved in your web testing and then create a work chart for accurate estimates and planning.