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?

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
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

• Types of Documentation
• Technical writing in general
• Technical documentation organization
• Writing instructions
• Writing user manual
• Reference guide organization

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 cant see the relevance of what they are
  reading in the context of the whole document
• Searchers cant 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 OR Loops/Ifs/Variables

7
Example of Technical Documentation Organization

• Java in a Nutshell, David Flanagan, OReilly,
  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 OReilly wanted to sell this book to C
  programmers
• and to programmers familiar with mostly Java
  1.0
• He thought programmers who didnt 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
Definitions

• Readers of technical writing dont 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

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
  readers 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 Dos and Donts

• Do use grammatical English
• Use spellcheckers
• You dont 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
• Dont 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
• Each step begins with some command word e.g.
  click select
• 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 lthostnamegt to be connected to
lthostnamegt
obelix11 open lthostnamegt (Note this will
connect you to lthostnamegt)
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 (its fun and easy to create an
  picture using Megasofts DrawingsRUs)
• Limit the companys 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 readers knowledge from less to more
• Make section 1 to be material which doesnt
  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 authors 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.
• lttablegt lt/tablegt Table Creates a table. The
  table is empty unless you create rows and cells
  using the lttrgt, lttdgt elements.
• Table element tag descriptions are given
  immediately following the table tag description
• Readers of technical writing who are
  knowledgeable dont 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