Teaching Staff
The aim of this course is to introduce students in the second year of the University of Brighton's computing degrees to the issues involved in designing and developing documentation for software and hardware products. It has no official prerequisites, but students will find it helpful to have followed the Desktop Publishing Module.
The course is process- as well product-oriented: in other words in addition to analysing end products such as paper manuals, on-line help systems, Web pages and so on, we talk a lot about how these products are planned and produced. In particular, we look at the way the documentation and software design and development processes are (or perhaps "should be") woven together so that both can be tested, evaluated and eventually packaged and shipped together. Along the way we dip into topics such as the psychology of reading, elements of graphic design, writing for an international audience, hypertext, managing translation, authoring tools and the organisational politics of life as a technical author.
Miscellaneous
Have a look at this site, where the world's worst manuals are held up to ridicule…
AND
If you were ever tempted to think document design didn't matter, ask Al Gore or alternatively visit this site explaining how the misdesign of the Florida ballot paper undermined democracy as we know it. Worth exploring the rest of the site too.
Tuesday 3.00 - 4.00 in W502 (temporarily lodged in W501 from 2.00 - 3.00)
Workshops/tutorials:
T1 - Tuesday 4.00 - 5.00 in W502
(or W212 for practical work)
|
The main resource for the course is the on-line information about the documentation job we'll be concentrating on in classes, the FABULA system. Click on the Fabula Wizard to go to the case study area.
|
The other major resource is the online help authoring system, DOT Help, which will be both a tool and a case study: your course work over the semester will involve creating new paper and online documentation for this system.
If you would like to buy a textbook to support the module (not obligatory) there are several options. One is Jonathan Price and Henry Korman. (1993). How to Communicate Technical Information (Benjamin Cummings). This is an attractive and practical book, informal and readable, full of advice for the technical writing neophyte, particularly good for the writer working as a consultant.
Another really excellent textbook, concentrating solely on software documentation, is Thomas T. Barker's Writing Software Documentation: a Task-Oriented Approach (Allyn & Bacon). This takes a user-centred approach very similar to the one we take in IS204.
Schriver, Karen A. (1997). Dynamics in Document Design. Another attractively produced book, but one that probably tells you more than you want to know at the moment about the academic status of technical writing in the US. An excellent and thorough source of information and references, though, especially on user analysis, psychology of reading, graphic design principles and the integration of illustration. This will very likely be the classic reference in the area from now on.
Tufte, Edward R. (1983). The Visual
Display of Quantitative Data. Envisioning Information and
Gorgeously designed and produced
books on graphic design and illustration. Try to spend some time in the
library looking at these. If you only have half an hour, look at the map
of Napoleon's retreat from Moscow in the 1983 book and be amazed.
Norman, D.A. (1990) The Design
of Everyday Things. Penguin.
Read this whenever you are tempted
to think that the reason people can't use your software is that they're
stupid. This book will also change your relationship to taps, light switches
and doorknobs forever.
James Hartley's (1994) Designing Instructional Text, 3rd edition, although primarily concerned with textbooks, is an excellent source of advice on the design decisions to be made for software documentation.
You may also like to get hold of a manual of writing, which will be useful throughout your career, whether or not writing is your main occupation. Two very popular and reasonably priced writing manuals are:
Strunk, W. and E.B. White. (1979).
The
Elements of Style. Macmillan.
Barrass, Robert. (1982). Students
Must Write. (Methuen) - available in the Library at 808.042.
On-line resources
Mantex Information Design - electronic publications and computer-based learning programs: a pot pourri of good information on a wide range of writing products
Society of Technical and Scientific Communicators (UK) - The professional organisation for UK Links to conferences, courses, articles, etc. Excellent section on standards.
Society for Technical Communication (US) - The US professional body, with searchable database of publications.
Technical Writing - a goldmine of information
Or carry out your own search here:
 |
Search WWW |
Tutorial: observing a new
software user using think aloud protocols
Reading: Schriver on connecting
two VCRs (pp. 228 - 246)
Here's an interesting account of
a
day in the life of a technical writer.
This session looks at the early parts of the design and development process, in which the technical writer uses the results of user, task and product analyses to put together a specification for the documentation and its components.
Tutorial: designing user scenarios
for case study
Reading: Alan Cooper on personas
In this session we look at the types
of document, paper and on-line, you might want to produce for a given software
product. We use a simple grid to clarify
the decision making process. We look at a library and a document specification
for the Fabula case study.
Slides
here…
For more
info on later stages of the process…
Assessment 1 is here.
In this session we examine some of the guidelines suggested for technical writers (avoid ambiguous terms, make references clear, avoid ellipsis, use simple vocabulary, avoid technical jargon, match sequence to order of tasks, etc.) and compare these to the advice students have received in the past about their personal and academic writing (write in paragraphs, use elegant variation, always include a finite verb, use sophisticated vocabulary, use complex sentence structure).
Tutorial:
Writing skills I - analysing and critiquing texts
Independent work: research
Web resources for support on writing strategies, grammar, punctuation,
professional organisations
For more details on the process of writing…
Graphic designers interested in usability use type and space not only to make the text literally readable but also to "engineer" the reader's interaction with the text, in the following ways (see also Schriver, p.250 ff for more in this vein):
Tutorial: Writing skills II
- procedures
Independent work: draft content
for procedures to be included in assessed work
Readers typically want to retrieve specific information for documentation, rather than read through a complete document. How should you design to achieve this?
Tutorial: Writing skills III
- making an index
Independent work: assessed
work
This week we look at the relative merits of paper-based and on-line help, concentrating on the problems of reading on-line, the varieties of on-line help (context-sensitive help, interactive tutorials, on-line reference manuals, animated help, intelligent agents, Web -based help) and browsing vs search strategies for hypertext.
Tutorial: analysis of on-line
help for a locally available system, e.g. Microsoft Word
Independent work: assessed
work
Tutorial: practical DotHLP
Independent work: learning
DotHLP
Here we look at structured writing systems based on a variety of mark up languages and discuss the advantages and disadvantages of taking a single-source approach to documentation practice.
Tutorial: DotCHM - HTML Help
Independent work: planning
on-line help system for case study
This session discusses the issues raised by linguistically and culturally diverse user populations and introduces the concepts of internationalisation and localisation, writing for translation and Controlled Languages. How does this relate to the case study?
Tutorial: Internationalisation
exercise
Independent work: begin to
implement on-line help system sections for assessed work
Christmas Break
Tutorial and independent work: completing assessed work
To
Lyn Pemberton's Home Page
Last edited 20 December 2002
