1 What do you look for when buying a manual? I.e. when you are hanging out in the computer section in Chapters, how are you deciding which books to purchase? How would you classify software books (into what types of categories)?

2 Documentation Types of Documentation Technical writing in general Technical documentation organization Writing instructions Writing user manual Reference guide organization “Documentation is like food; when it's good, it's very, very good, and when it's bad, it's better than nothing.” – paraphrasing Dick Brandon

3 Types of Software Documentation Internal Documentation Comments in source code Help facilities within program External documentation User manuals Setup and installation instructions We will assume you know how to write comments in your code Here we will concentrate on the other things

4 Technical Writing Written text which addresses things like: What one has to do in order to accomplish something What is known about a particular topic People use technical writing when: They need to find out about a topic they know nothing about They need to find out more about a topic they know a little about Two basic modes of using technical writing: Browsing; the reader flips through or reads through the pages, hoping to get an overall idea of the content Searching: reader searches for a specific piece of information Technical writing should: Present material in a way that is easy for the reader to digest Organized material in order to help the reader find things easily Remember, the reader may not know anything about the topic before reading it.

5 Organizing a Technical Document It there is no structure to the document, every page looks like every other page Browsers can’t see the relevance of what they are reading in the context of the whole document Searchers can’t find what they are looking for easily. Techniques for organizing documents: Clear chapter names, section names, headings, subheadings, paragraph headings (“units” of the document) Table of Contents Index Most word/text processor packages can produce these things for us automatically Still, tables of contents, etc. are so useful that they should be produced by hand if necessary.

6 Dilemma In Java Introduction Books: Which do you cover first in your book? Objects Concept ORLoops/Ifs/Variables

7 Example of Technical Documentation Organization Java in a Nutshell, David Flanagan, O’Reilly, 1997 Table of Contents Preface Part I: Introducing Java —Gives tutorial introduction to Java for people more familiar with C Part II: Introducing Java 1.1 —Describes features in Java 1.1 not in 1.0 Part III: Programming with the Java 1.1 API —Contains chapters on applets, events, beans, serialization, etc. Part IV: Java Language Reference —Syntax, HTML tags, JDK tools Part V: API Quick Reference —Chapters on each of the main packages Index Each Part contains 2 to 16 chapters

8 Example of Technical Documentation Organization Continued There were other ways to organize this material Flanagan presumably chose this organization because: He knew O’Reilly wanted to sell this book to C programmers… … and to programmers familiar with mostly Java 1.0 He thought programmers who didn’t use (e.g.) serialization yet would want to find out about it in a self-contained chapter He knew programmers need details of syntax, declarations of APIs of packages, etc.

9 Readers of technical writing don’t start out knowing the subject. All terms which user is not likely to know should be defined in the document, Definitions can be either: “in-line”, that is inside the normal text —E.g. “An abstract method is a method that has no body, only a signature definition followed by a semicolon” In a separate glossary section A definition should: Use words that the user understands already —E.g. the above definition of abstract method: good only if reader already knows what a signature definition is Express clearly what distinguishes it from other related concepts —E.g. that the method has no body Not be circular —E.g. an abstract method is a method which is abstract Not just refer to what it is used for —E.g not “an abstract method allows different implementations of the same method in subclasses —Above is fine as part of an explanation, but not as a definition Definitions

10 Examples An example is worth a thousand explanations They usually follow a more technical explanation of the concept; e.g. “An abstract method is a method that has no body; only a signature definition followed by a semicolon. For example: public abstract double area(); declares area as an abstract method” Examples can also precede a more technical explanation In this case, the example helps to focus the reader’s attention to clarify the explanation; e.g.: —“Consider the following declaration: public abstract double area(); This declares area as an abstract method; that is, a method consisting of only a signature definition followed by a semicolon.” They are improved by diagrams, pictures, etc.

11 General Do’s and Don’ts Do use grammatical English Use spellcheckers You don’t have to have complete sentences all the time However, sentence fragments should be easy to read and unambiguous Do remember your audience Keep mentally checking whether the intended reader would really be able to use what you have written. Do use a consistent writing style Don’t switch from first person to second person Do use some kind of introduce for each unit of the document Introductory chapter for book, introductory paragraph for section, brief description for command Should give the reader a summary of the whole unit and/or background information they need to know Lets the reader see where the document is going Makes the material easier to digest once it is encountered Helps the reader find things later in the unit Use different fonts consistently (explain what they are)

12 Writing Instructions Instructions on “how to do things” are common in user manuals A common organization for a good set of instructions Introductory paragraph describing the purpose of instructions Point form list of simple individual steps —E—Each step begins with some command word; e.g. “click” “select” —P—Points may be numbered Explanatory notes should be separated from the instructions themselves; e.g. Not Rather lay it out like this: Validate your instructions!!! Go through them in the real world and make sure they really work Enter open to be connected to obelix[11]% open (Note: this will connect you to )

13 User Manual User Manual: Text intended to help the user of some product (software, hardware, etc) Reader = User, User = Reader User manuals may have many purposes: Inform the user about how to use the product Sell the product (“it’s fun and easy to create an picture using Megasoft’s DrawingsRUs”) Limit the company’s liability for the product User manuals that come with commercial software products are not the greatest examples Sometimes seem to be included only because user expects them Companies rely on publishers of books like “DrawingRUs for Morons” to write good manuals, tutorials.

14 Material in a User Manual Generally two kinds of material appear in a user manual: Tutorial Material —Text which teaches the user about the concepts needed to use the product —Instructions walking the user through details of how to do specific tasks Reference Material —Details of purpose and intended use of every individual button, command, dial —Declarations of individual functions in an API Usually both are necessary Facilities of product can usually be used in a variety of different ways Without tutorial material, user would have to piece together the overall picture Without reference material, user would have trouble finding information on specific topics Help facilities in program usually of the “reference” type

15 Writing Tutorial Material Build reader’s knowledge from less to more Make section 1 to be material which doesn’t depend on anything Make section 2 that depends only on section 1 Etc Go from specific to general or general to specific Use an example followed by / preceded by more general discussion Discuss a special kind of task (e.g. setting the VCR to record now), then a more general task (e.g. setting the VCR to record at a particular time) or vise versa Introduce each section, paragraph, etc. with something which Tells the reader what they are going to learn in the section Gives the reader any background information that they need to know

16 Example of Reference Manual Organization Hip Pocket Guide to HTML 4.01, E. Tittle, J.M. Stewart and C. Valentine, IDG Books Worldwide, Inc, 2000 Table of Contents Preface Chapter 1 —Gives a brief history and overview of HTML syntax for novice Web page designers Chapter 2,3,4: —Lists the categories of HTML tags, on which the organizational scheme for Chapters 3-14 is based —The standard sections that make up a tag definition that is used in those chapters are also described Chapter 5-14: —Tag definitions by category Chapter 15: —Covers the use of the different standard characters sets that can be displayed on a Web page using HTML Appendices —Tables of commonly used tools, attributes, colours —Where to find extensions to HTML (plug-ins, applets) —A list of the author’s favourite web tool software packages Index

17 Example of Reference Manual Organization continued There were other ways to organize this material E.g. tags could have simply been listed alphabetically The authors presumably chose this organization because: They intended the book for people who had some understanding of what functions can be provided in a Web page (i.e. not Internet illiterate!) … and to Web designers familiar with earlier versions of HTML who need a tag reference guide that is well organized and up to date. They kept the overview and tag summary brief, just giving the essentials with very few examples However, each of the 91 tag definitions include a pertinent example… … and many of the category chapters give resource web sites in their introductions

18 Writing Reference Material Typically, consists of lots of little sections E.g. one for each tag, button, command, method etc Can be organized in a hierarchy of document units Present similar things in consistently similar ways E.g. description of an HTML tag: —Heading with tag or tag pair and its name —A brief definition of the tag, explaining purpose, function and effect on document —Definition and usage of each attribute that can be used to modify the features of the tag —A list of the contexts (i.e. other tag pairs) within which the tag can legally appear —Some style/usage tips —An example of the use of the tag, with some attributes followed by a screenshot Every tag would be described in this way

19 Definitions in Reference Manuals Definitions can be given in a hierarchy where appropriate, e.g. “ … Table: Creates a table. The table is empty unless you create rows and cells using the, elements.” Table element tag descriptions are given immediately following the table tag description Readers of technical writing who are knowledgeable don’t need to have every term defined However, a definition should still: Use words that the reader understands already, i.e. general terms a reader would already know from past experience or that have been previously defined in the text, e.g. —The above definition of the table tag is good only if reader already knows what the other 3 tags do —A list of tags covered with a brief definition of each is given at the beginning of each chapter —However, the terms table, row and cell are not defined since they would already be familiar to anyone who has used a word processor

20 Another Example from a Web Page:

21 And Finally… Keep the reader in mind Keep re-reading what you have written to check it Look at documents that you have found helpful and emulate them