Software User Documentation CSc 191 Senior Project Software User Documentation

Atkinson’s Third Law “If you need to read a computer manual, you can’t. If you can read a computer manual, you don’t need to.” “It’s the Law!”, Computerworld, August 12, 2002

Track Record… Muddy! “… some very bad user manuals have been written.” Software developers have, evidently, had a difficult time thinking like a user. One solution… bring in the technical writers.

Technical Writers Manuals are definitely more readable. However, two new problems are created… 1. answers to some questions are not documented… and can only be answered by understanding the software product, which is beyond the reach of the technical writer. 2. implementers will be interrupted!

How to Spot a Bad User Manual? Poor organization and poor writing. Tries to do too much… not focused on user needs… contains information the implementers care about. Reads like a sales brochure. “In the past, little emphasis has been placed on the value of the User Manual… but today, mass marketing of consumer software has provided motivation for improved and innovative approaches.”

How & Where to Begin Identify required user documents: First, identify the audiences that will use the product. Then identify the document set for each audience and the usage mode of each document. Do this before planning and writing. The identified audience will dictate the document presentation style and level of detail.

Document Usage Modes Instructional Mode Reference Mode For users that need to know how to use the software Reference Mode For users that need documentation to learn about the software

Instructional Mode Documents Provide background and information needed to understand the system. Provide information needed to learn what can be done with the software and how to use it. Provide examples to reinforce the learning process.

Examples Instructional Mode Documents: Information-oriented introductory manual theory of operation manual tutorial Task-oriented diagnostic procedures manual operations manual software installation manual training manual / user manual

Reference Mode Documents Purpose Organize and provide necessary information Facilitate random access to information

Examples Command manual Error message manual Program calls manual Quick reference guide Software tools manual Utilities manual Reference manual

To help people carry out certain tasks Generic Structure All manuals have one thing in common: To help people carry out certain tasks the manual must fit the needs of the user, not the structure of the product! the manual must be organized to reflect the way in which the user will work with the product. Reference: Writing Software Manuals: A Practical Guide, Martyn Thirlway, Prentice-Hall, 1994.

Online versus Printed Documentation Four “obvious” differences: 1. Ease of Reading 2. Portability 3. Audience Perception 4. Accessibility

Translated Documents (for the non-English Speaking Market) Write the kind of English that is easy to translate! Avoid: cultural references emotion, humor and slang abstract words excessive nominalization (“terminal emulation configuration tool” should instead be “tool that helps you configure for terminal emulation”) long sentences and paragraphs unexplained technical words or phrases figures of speech highly complicated grammar (subjunctive…) ambiguity of any kind

Complicated… The Subjunctive: If I had the money, I would buy the… If I get the call in time, I will go… If I had gotten the call, I would have gone… The “fun” part of learning a new language 

Design Principles Maintain consistency. Write stand-alone units. Determine the quantity of information to display.

Why User Documentation? ( recap ) Provides the information necessary to make the software product useful to the user. Provides specific answers to the following: What capabilities does the product offer? How and where can the product be accessed? What input must be prepared to use the product? What output will be produced and how is the output interpreted? What limitations and restrictions does the product have? What resources does the product use (time, main memory, external storage)? What error diagnostics are there, and how should the user respond to them?

Bad Some ^ samples... “Type the field name Name in the Field Name field.” “Access the ADJUSTMENTS dialog by click king the Trial Balance tab, and then the Adjustments sub-tab.” “Warning! The Unauthorized Misusage of Data is Prohibited.”

Some more... “[some action is taken] on the third non-consecutive day [that some event occurs].” “This 15” auto-scan monitor which will operate from VGA to highend windows and CAD/CAM applications.” “The following table below is arranged alfabetically in numerical order.”

You could “graduate” to the following... From a British military publication: “It is necessary for technical reasons that these warheads should be stored with the top at the bottom and the bottom at the top. In order that there may be no doubt as to which is the top and which is the bottom, for storage purposes it will be seen that the bottom of each warhead has been labeled with the word top.”

Software User Documentation Extra credit assignment: Find an example of “User Documentation” that is either good or bad. The example should not be an entire document, but a specific example… no more than one page! Either copy the “page” to hand-in, or type the example. On a separate page, briefly explain why you consider the example to be either good or bad.