ICAD3218A Create User Documentation

Before starting to create any user documentation ask ‘What is the documentation going to be used for?’.

When you are satisfied that you have an answer, you can then decide what type of documentation you are going to produce.

When developing documentation it is important to understand the user’s requirements to know which medium is preferable. In a lot of cases both printed and online forms may be required.

A needs analysis is a process where the needs of the target groups for the documentation are identified and analysed. This analysis helps to make decisions on what the documentation should contain and what format is most suitable

Once the needs analysis is completed, learn what the intended user requires. Do this by becoming a user so that you become familiar with its features and you are confident in using it.

look at:

The functionality — how it works The work processes surrounding its use —

how the system works with organisational processes and procedures.

Document Blueprint

Provide the information the authors need to produce the documentation.

This occurs in the Planning stage of the standard documentation process.

The individual document specification covers the document’s, Purpose, Audience, Related documents, Media, Production plan (eg. Published internally or externally), Reviewing and testing, Update plan

Creating a document library blueprint involves identifying all the pieces of documentation and how they are related, and developing a specification for each known as the document specification.

Reviewing Process The review process is generally outlined in the

organisation’s policy or the project documents.

Reviewing involves checking over the document.

The review process varies from organisation to organisation and project to project. The review process is generally outlined in the organisation’s policy or the project documents.

Consider the following factors when identifying the intended user of your documentation:

level of computing experience experience with the particular system or application frequency of use with a particular system or

application workplace tasks work practices and environment language skills cultural background personal characteristics such as aptitude, educational

background, age, disability level of confidence

Types of media for producing documentation Paper documentation (print media) Static on-line documentation Dynamic on-line documentation

A template is a file that contains a standard layout, styles and fonts that are used in the production of the documentation.

Using a template ensures there is a consistent look and feel to all of the user documentation. It saves time.

Some of the software tools used to produce online documentation include:

Frontpage Notepad Microsoft Word

Different forms of documentation are more suitable than others for the level of the intended user. For example, the forms of documentation most suitable for a novice user would be a Printed handbook

The standards used to create user documentation include Industry standards and/or organisational policies

When creating user documentation consider the users requirements. Computer literacy , Experience with a system or application and Existing work procedures

When ‘sign of’ is required, it involves each of the key stakeholders reviewing and approving the documentation.

Online documentation would be considered if a user requires documentation which is convenient, accessible (to many people worldwide), can contain links to other related documents and is easy to maintain and update.

Types of on-line documentation include WebPages (HTML), PDF (Portable Document Format), user forums, FAQ (frequently Asked Questions) and Online Help Files.

The 3 levels of users that the publishing world generally recognises novice, intermediate and advanced users.

Version control Version control is used to ensure that changes are

not lost and versions are not confused. This will often be outlined in the user documentation policy.

Either way, it is critical to establish how you are going to name and number the various versions of your documents and to communicate that process to other writers and reviewers so that everyone is on the same page.

There are many principles of document design which should be followed when designing user documentation. These include

Appropriate medium to the task

Give a brief introduction where you state the purpose and objectives of the documentation.

Include a table of contents or index.

When writing, keep the users’ needs in mind, ie put yourself in the users’ place.

Ensure the content is accurate.

Make clear sections for different types of features/information.

Break the content down into easy-to-digest ‘chunks’, eg using paragraphs and sub headings, or multiple screens.

Use illustrations, diagrams, charts and/or screen shots where appropriate.

State instructions clearly and step-by-step.

Use plain English and avoid jargon.

Use technical terms only where necessary.

Include a troubleshooting or help section.

Include a glossary of the technical terms you have used.

Make the document structure as simple as possible and logical by providing cues to locate information.

Ensure good usability, especially for online documentation.

Cross-reference information, eg use hyperlinks in online documentation.

Warnings, comments and help should be well-organised and visible.

Aim for a clean design for text styles and layout that is consistent across all pages.

Reviewing Process The review process is generally outlined in

the organisation’s policy or the project documents.

Reviewing involves checking over the document.

The review process varies from organisation to organisation and project to project. The review process is generally outlined in the organisation’s policy or the project documents.

ISO stands for International Standards Organisation

A Quick Reference card is not Online documentation

The Technical writer is responsible for writing the user documentation and submitting it for review.

Web based documentation includes User forums, Frequently asked questions and HTML files

Types of User documentation include

Instructional material Training material Policies or procedures documents Reference documentation FAQ’s Reports Help resources User manual/guide Self-paced tutorials and Brochures