EN 3164 English for Information Systems
Student Manual
(2000-2001)
Learning to Write User Manuals
and
Plan and Present Technical Training
Prepared by
Becky Kwan
Department of English
City University of Hong Kong
PREFACE
================================================================
Documentation of software and hardware refers to the writing of instructional materials
(e.g., technical product description, manuals, quick guides and trouble shooting manuals)
for users of in-house computer products. End User Computing Training (EUCT) refers to
the training for users of any computer products (e.g., software, hardware, and systems).
EUCT takes on many forms: college training, company training, and vendor training.
Documentation and EUCT are crucial to effective computer systems utilization. Without
them, new software and various forms of technological enhancements can never be
mastered successfully. In fact, EUCT and documentation have in the past decade evolved
into a new discipline of its own, which draws on theories and knowledge from various
disciplines of information technology, psychology, education and communication.
Trend of EUCT and documentation writing
Information technology has been developing at an exponential rate. Within a span of only
40 years, the information technology industry has already gone through three critical eras
of mainframes in the 60s and 70s, the explosions of PCs and desktops in the 80s, and now
information superhighways in the 90s. New versions of products emerge and outdate
their former generations at such a dizzying rate that creates in the user community a
never-ceasing demand for EUTC and documentation to cope with the mastery of new
products.
EUCT and documentation as job requirements or a career
In-house training and preparation of documentation have in recent years received much
attention by EDP (Electronic Data Processing) units of many big corporations and
education institutes alike, City University of Hong Kong being one of them. Consulting
firms and free-lance consultants have sprung up to cope with the demand of training.
EUCT and documentation writing in fact make up two major areas of work in many jobs
related to information technology. With a right mix of aptitude and sufficient training, an
IT professional can consider developing his/her career along the line of EUCT.
Course description
To add to your competitive edge and professional versatility upon graduation, this course
aims to develop your basic skills to plan and produce effective software manuals, and to
conduct effective training. It also aims to develop your English proficiency. Skills
learned in this course are transferable to some other IS courses.
About this Manual
This manual is written specifically for use in the course of EN 3164 of the BBAIS
program at City University of Hong Kong. Adapted from a previous version of manual
for the module written by Robert Hoffman, this manual contains notes, exercises and
tasks that guide you through the learning of various principles of manual writing and
workshop presentation.
i
Basic features
The manual is divided into 12 sections, each of which is divided into two parts (except
for Section I). The first part covers some basic principles related to the topic of the
section. The second part is a file of tasks and worksheets, which guide you to learn and
practise the principles covered in the section.
How to use it?
Study the instructional schedule in Section I.4 for the weekly reading and writing
assignments before the class of each week. The criteria for assessment of various
assignments are largely based on the principles covered in this manual. Make sure you
refer to the relevant parts from time to time when working on the various assigned tasks.
ii
TABLE OF CONTENTS
===============================================================
i
PREFACE
SECTION I
INFORMATION ABOUT THIS MODULE
Aims and Objectives
I-1
Topics
I-1
Marking Scheme
I-2
EN 1244 Schedule
I-3
Instructions of Tasks
I-4
SECTION II
SECTION III
SECTION IV
SECTION V
SECTION VI
USER MANUALS
Purposes of user manuals
General structure
Types of user manuals
General characteristics of formatting and appearance
Tasks File
II-1
II-3
II-3
II-5
II-6
AN OVERVIEW OF PRODUCTION PROCEDURE
General procedure
Needs and audience (user) analysis
Contents selection
Contents organization and tables of contents
Tasks File
III-1
III-1
III-3
III-3
III-6
WRITING THE PREFACE
Contents
Tasks File
IV-1
IV-5
STRUCTURING A SECTION
& WRITING INSTRUCTIONS
Organization of a section
Introductory texts in a user manual
Writing instructions
Collective vs component steps
Supplying examples
Supplying graphics (See also Section IX)
Follow-up tasks in tutorial manuals
Tasks File
V-1
V-2
V-2
V-3
V-3
V-4
V-4
V-5
EXPLAINING TECHNICAL TERMS
What terms to explain?
Where to explain them?
What to write?
Language for writing explanations
VI-1
VI-1
VI-1
VI-2
iii
Organizing the glossary
Tasks File
SECTION VII
VI-2
VI-3
EDITING TO ENSUR READABILITY
Use of Language
Use of symbols + conventions + graphics
Tasks File
VII-1
VII-2
VII-4
SECTION VIII PROOFREADING & AWARENESS OF LANGUAGE
ACCURACY
Tasks File
VIII-1
SECTION IX
SECTION X
SECTION XI
SECTION XII
FRONT / END MATERIALS & USSE OF GRAPHICS
Contents and Formatting of Front / End Materials
References made to graphics (i.e., non-text materials)
IX-1
IX-2
PLANNING TECHNICAL TRAINING WORKSHOPS
Some facts about training and on-line help
Manuals and face-to-face / real-time training
Product sales presentations, demonstrations & workshops
Why do people join IS / computing training workshops?
What makes a professionally run training workshop?
Preparing for a training workshop
Tasks File
X-1
X-2
X-3
X-4
X-4
X-5
X-7
DESIGNING MATERIAL AND ASSESSMENT
Workshop title, overall aim and objective statements
Teaching and learning activities
Materials preparation
Assessment
Evaluation
Tasks File
DELIVERING TRAINING WORKSHOPS
Workshop structure
Workshop plans
Delivery skills
Language for workshops
Tasks File
iv
XI-1
XI-4
XI-6
XI-6
XI-7
XI-8
XII-1
XII-1
XII-3
XII-6
XII-9