01 What are the standards you may use to write user documentation?

Activity 1

Source:

http://web1.keira-h.schools.nsw.edu.au/Faculties/IT/year12/IT%20Cert3/lo/1499/1499_00.htm

http://www.hci.com.au/hcisite2/journal/Proposed%20new%20international%20standard%20for%20user%20documentation.htm

What are the standards you may use to write user documentation? (Select one.)

• Industry standards and/or organisational policies

What is the ISO? Explain.

• International Standards Organisation. This is a global organisation that produces standards. Members are government bodies, industry associations and private organisations that have an interest in industry standardisation. They reach consensus on standards for industries that meet the needs of both industries and consumers.

What is IS15910? Explain.

• An ISO/IEC standard for user documentation. The ISO standard IS15910 outlines the way user documentation should be planned. This standard is designed to be part of a contract but there is a new standard (ISI8019) that will not have this restriction.

What is the Australian standard for user documentation? 200 words.

• Standards Australia is our organisation for the development of national standards. It has been in existence since 1922 and is a member of ISO and IEC. Members represent groups who have an interest in the development of standards through committees of special interest groups. Standards Australia has developed its own user documentation standard that is based on the ISO/IEC standard. It is called AS4258. It outlines the processes for creating all forms of user documentation for software and can be used as a contract with external customers or between internal customers.

Activity 2: Identify user documentation standards

1. Go to the Standards Australia website at: http://standards.org.au

2. At the website, click on ‘Search for a standard’ and search for ‘User documentation’.

The search will display a number of standards. You will find a detailed description of the standards in the Scope and Abstract notes.

Choose three standards and list some points to describe each one.

AS/NZS 4258: 1994

Australian/New Zealand Standard

Software user documentation process

This joint Australian/New Zealand Standard was prepared by Joint Technical Committee IT/9, Information Systems Vocabulary and Software. It was approved on behalf of the Council of Standards Australia on 14 September 1994 and on behalf of the Council of Standards New Zealand on 24 October 1994. It was published on 14 November 1994.

AS/NZS 4598.1: 1999

Australian/New Zealand Standard

Guide to the development of application software

Part 1: Software user documentation.

This joint Australian/New Zealand Standard was prepared by Joint Technical Committee IT/15, Software Engineering. It was approved on behalf of the Council of Standards Australia on 14 July 1999 and on behalf of the Council of Standards New Zealand on 28 June 1999. It was published on 5 August 1999.

AS/NZS ISO/IEC 15910: 2004

Australian/New Zealand Standard

Information technology - Software user documentation process

This joint Australian/New Zealand Standard was prepared by Joint Technical Committee IT-015, Software and Systems Engineering. It was approved on behalf of the Council of Standards Australia on 19 March 2004 and on behalf of the Council of Standards New Zealand on 7 May 2004. It was published on 1 June 2004.

02 Determine user documentation requirements

Activity 1

Useful documentation

Useful for learning new software Not so useful for learning new software Online help Technical manual Training manual Systems diagrams User guide Project specifications

User characteristics

We need to take into account factors that relate to users and their work environment.

Which factors matter?

• Computer literacy, • Experience with a system or application, • IT systems, • Literacy level

Choosing documentation media

Identify the advantages of paper-based versus online documentation.

Advantages of paper-based documentation Advantages of online documentation no specific equipment required reaches many users transportable cheap to produce interactive produced with generic software convenient to use at computer transportable easy to update

Activity 2: Recommendations for user documentation A needs analysis has discovered the following factors behind the introduction of new a software application: A new software application for customer services is being introduced into a company that has users all over the country. This new application is part of structural changes that require new work processes to also be introduced. The company has not yet used online training or reference materials but wishes have online a reference for the first time. What broad recommendations could you make for this company’s user documentation? My recommendations for this company’s user documentation will be:

• Make a paper-based documentation for users who do not have knowledge about on-line documentation.

• Divide different groups according to the software knowledge they already have. • Design a friendly interface, easy to use, just with the content that is needed to learn the

new software application. • Hire expert professionals in User Experience and User Interface for the making of the user

documentation. • Introduce the documentation of the new software application with enough time for the

learning of all the users in the company and take a test to the users before the software is launched all over the country.

• Make a formal presentation of the new software and its documentation in each part of the country where the company have users and answer all the frequent questions that the users could have.

03 Produce user documentation

You are going to write a user guide for a new application. You have just conducted an analysis of the needs of the end users. What are the first steps you will take?

• Interview the Project Manager and project team members

Which of these tools can be used to develop online documentation?

• A word processor, an image editing application, a HTML generator or a slide show application can be used to develop online documentation.

Activity 1: What makes a good user guide?

In your home, locate a manual that you think is effective for how to use one a home appliance or other technical equipment, such as a microwave, clock radio, DVD player, computer peripheral, etc.

Look at the manual and try to identify features that make the manual a good ‘user guide’. List those features.

Some of those features may be: (8 answers)

• Consistent appearance and layout • Clear bold headings • Index • Pictures • Diagrams • Conventions • Chapters • Highlights

Activity 2: Usability

Using the same manual you found for Activity 1, conduct a usability test. For example, think about some specific information you want to find and see how easy it is to find it.

Why was the information or instruction easy or difficult to find?

A manual may have good usability due to: 4 answers

• The features mentioned in Activity 1 • The pagination • The organization of the information in chapters • Subtitles

A manual may have poor usability due to: 3 answers

• No index or table of contents (navigation) • No specific steps • No a clear start or finish

Activity 3: Types of documentation

Can you think of any other types of documentation that may be used to support a software application or other software (apart from user guides)?

Some more examples of documentation are: (4 answers)

• Quick-reference cards • Brief • Tutorials • Videos

Activity 4: Online documentation

Increasingly, documentation is provided online, e.g. on a company intranet, where staff can access this information for themselves.

Can you think of advantages of having documentation available online? (2 answers)

There are many advantages to online documentation. Having centralised online documentation means:

• It can be accessed by staff as and when they need it meaning improved client efficiency and satisfaction.

• It does not need paper to be made therefore contributes to the ecology.