Great User Documents Course
Active Table of Contents. A Table of Contents (TOC) in an electronic document, which permits the Reader to click on an entry in the TOC and jump to the relevant page in the document.
An All-Graphic User Document is one where there is little or no writing; all of the material is presented by graphics.
Bold. A text modification in which the text is drawn with slightly thicker lines. Bold text draws the Readers’ eyes to it. Thus it should be used to enhance text which you use as informal headings which are just words in the text. Do not use bold to emphasize text. Instead use italics or underline. We use bold text to act as internal headings in our writing to draw the Reader’s eye to topics that they might be searching for.
Notice how in this Glossary, the terms being defined are in bold. This assists you in finding a desired word.
Component. A component is a piece of the outline of User Document that you have selected to write about. It may be a single item on the outline, or several items. You will have to decide how many outline topics to include in a Component.
You will write the material for the Component, review ands revise it, and then publish it internally for your Components Readers. You will solicit and receive feedback on the Component. You will revise it and then polish it for final publication.
Ultimately someone will write all the Components for the User Document.
Components Readers. You will write the Components of your User Document in sections, chunks or whatever, that I call Components. When you are moderately happy with the rough draft of the Component you will publish it internally for the Designers, Developers, Subject Matter Experts and whoever else you select to read and comment on the Component. These people are what I call the Components Readers.
Contraction. A word or group of words resulting from shortening an original form (Oxford dictionary). Some examples are:
you would you’d
are not aren’t
can not can’t
Don’t be afraid of using contractions in your writing (see, I just did it!). They make your writing more informal, and more like your Reader speaks. This informality leads to greater acceptance by your Reader.
Demote. (Concept for outlining) Demoting a heading in an outline lowers it one or more levels. It makes the topic “less major.” Visually, in an indented outline, demoting a topic will cause it to be moved to the right, making it look more indented.
Draft. Any working copy of your document. All working copies of your document up
until it is published. And when you
take a final copy and make changes in that copy, then it becomes a draft.
Editor. See “ProofReader,” below.
Graphic. As in "include a graphic." I use "graphic" as a generic term, which refers to any non-textual material that you include in your document. "Graphics" includes sketches, photographs, flowcharts, and tables; anything that's not text.
High Level Outline Document. This is simply the word processing file where you store the overall outline of the User Document. It will contain the high level topics of the User Document's outline. As you write the Component (in its own word processing file) you put the file name of the Component's word processing file in the appropriate place in the High Level Outline Document. The purpose of this is to keep the structure of the entire User Document visible as you work on each Component of the document.
An example of this is the way this Course is arranged. The Course Home Page shows the overall outline of the Course and where relevant, contains links to the written Components of the Course.
In-Line Definition. An explanation of a phrase or term that appears in the text of the User Document, where the phrase or term is first used. The explanation may be in parentheses or as a separate sentence or paragraph. I advise putting the phrase or term and its definition in the Glossary of the User Document, if you choose to provide one.
Internally Published Components. In this Course, as you create your User Document, you will publish chunks of it on an internal site (or e-mail it) for others working on the product to review. These Chunks of the User Document are called "Components" and those on the product are your Components Readers.
Internet Supported Product. A product that is (in my opinion) properly supported by Internet Web pages. "Properly supported" includes:
O Easy to find the relevant Web page for the product
O The Web page is quick to load, easy to use and navigate (no fancy graphics, animations, etc)
O The Web page has links to the User Documentation, (possibly) Technical and Repair Documentation, Tips, Upgrade Information, and support contact.
(Igetitnow! Training, Inc. is planning a Course on making products Internet Supported Products.)
Iterative, Interactive Writing. A writing method where the author selects a portion of the document (which we call a Component), writes about that, and publishes it internally for the Components Readers (interactive aspect). The author accepts and incorporates the Components Readers' comments and suggestions into the writing. The author then internally re-publishes the Component, and the interactive cycle continues. This process should iterate for a maximum of about three cycles.
Legend: A box in a graphic that explains the symbols used in the graphic. Most maps include a legend to explain the various map symbols.
Link. An item (perhaps a word, phrase or graphic) that if the User clicks on it will cause another part of the document or another document to appear. Typically the User can return to the link by using a “go back” facility in the viewer. The link brings the User to what some word processors call a bookmark.
Metadata are data that describe other data. Metadata is information about your writing which may include: Author, Publication Date; Topic (keywords), etc. These data are usually hidden, but can be searched (for reuse) by a content management system. See Wikipedia's description of Metadata.
Noun. A word that names a person, place or thing.
Points of Interaction. A Point of Interaction is any part of your product that signals or informs the User as well as any part of your product that accepts input (action) from the User. The term for all the Points of Interaction taken together is the product’s User Interface.
Promote. (Concept for outlining) Promoting a heading in an outline raises it up one or more levels. It makes the topic “more major.” Visually, in an indented outline, promoting a topic will cause it to be moved to the left.
Pronoun. A word that takes the place of a noun. Be careful with pronouns because unless things are perfectly clear in the Reader’s mind, he/she might not know what the pronoun refers back to. It might be a better policy to repeat the noun, rather than use a pronoun in an unclear way. My example in the text: “Tom and his father went fishing. At the end of the day, he was covered with mosquito bites.” Who does “he” refer to, Tom or his father?
ProofReader. A person who reads over your writing, and suggests changes in the writing to improve its clarity and grammar. I equate “proofReader” with “editor.”
SAKE This is an acronym for Skills, Attitude, Knowledge and Experience. We use these four dimensions to describe our Reader. Rather than talking about what a Reader knows, we use the acronym SAKE to describe the four-dimensional characteristics of our Reader (and User of the product our documentation supports). For more information see our discussion on the Describe Your Reader.
Segment (of your text). I can only use an example to explain this very flexible
concept. A segment is a very variable length block of text in your
document. Suppose a Reader jumps
into a section of your text. This can happen by any means: from a topic search, Table of Contents,
index, or thumbing through pages.
Let's assume that the Reader has a question that he/she wants to have
answered. That's why they jumped to a
page in your document.
Set-up SAKE. The Skills, Attitude, Knowledge and Experience that User needs to set up or install the product. The Set-up SAKE may include mechanical or other skills that are not need by a User of the product. We discuss this in the "Preparing to Use the Product" section of this Course.
Style. (As it relates to wordprocessor software.) A set of formats (instructions about how the text will appear) that can be applied to text in your document. A style can deal with how a paragraph will appear on the page as well as how the format of the text in that paragraph. But a style goes further than simply the format of the text. Styles have names, such as "Heading 1", "Body Text", etc. When you define the appearance of text using styles, the wordprocessor will ensure that everything of a particular style in the document looks the same; changing the definition (formatting rules) of a style will cause all text in the document of that style to change its appearance based on the change. Styles go even further; they enable the wordprocessor to understand your document. By using Heading styles (enforced when you create your document using the wordprocessor's outline capability), the wordprocessor will be able to easily generate a table of contents.
Always use styles to define the formatting of your text (the only exception might be when you want to simply bold, italicize, or underline some text.
Style Sheet. A style sheet is a list of decisions about how words and phrases are used, spelled, capitalized, and displayed in your document. It supplements a Style Manual that is a book of such decisions all made for you. Adopt a Style Manual very early in the writing project.
Synonyms. Two or more words (or phrases) that have similar meaning. For example, the words "format," "layout," and "appearance" are synonyms. They are important to you as a writer because your Readers will use their own words -- their synonyms -- when they search your document to find the information they need. You must include synonyms in your index and in the text of your document (as I describe in the Course section on Access). Adding the synonyms enables your Readers to find the information in your document more quickly, as they will be able to find the information based on the wording that they know and use.
Task-Based Documentation. User Documentation that is based upon what the User needs to and wants to do with your product. This is in opposition to product-based User Documentation where the documentation is based on the capabilities (and functions) of the product.
Text. The words you write.
Topic. Any subject you are going to write about (or mention) in your document. Any item of interest that you feel you should include in your document. No matter if the topic is a major subject of your document or a sub-sub-sub-topic of your document, we shall call them all “topics.”
Topics may be broken down (as you feel the need) into sub-topics to make the writing and reading easier. Within each topic you have some ideas or concepts or information (choose your favorite word) that you want to get across to your Reader. You will do this by creating sub-topics or doing the actual writing for this topic, as you decide. In other words your question is “should this topic be broken down into sub-topics, or should I write about it as a whole?” And the answer is up to you.
Topic Hierarchy. As you generate the topics for your document, and as you organize them, you will create a Topic Hierarchy. A Topic Hierarchy is an outline of the topics in your document. Outlines are hierarchical; they consist of higher-level (more important, if you will) topics, and under them subtopics that contribute to the higher-level topics. And so on under them.
Usage Thread. A path that a User takes to reach his/her goal with the Product.
Use Case. A Use Case specifies a set of goal-defined (the User wants to do something with the product) interactions between an Actor (the User, in our situation) and the product. An analyst typically writes use Cases. Compare this to User Stories, below.
User. The person (and I will assume that we are dealing with people) who employs your product to meet a goal of his/her own. Possibly one of the "arts" to writing User Documentation is to determine what are the User's relevant goals (and tasks) with your product. When creating User Documentation, always think in terms of the User.
User Story. A User Story is an interaction with the product as specified by the User. Instead of analysts creating the Use Case (which is much more formal that the User Story), the intended User creates the description of the interaction. Typically the User Story has at least two components: 1. The goal of the interaction. 2. A brief scenario of how that goal is achieved with the product. A comparison of Use Case and User Story is described at: http://c2.com/cgi/wiki?UserStoryAndUseCaseComparison
Visual Index. A visual index is a picture (or pictures) of your product with all components of the product labeled, and with page references (or links) in your document where your describe each of the components. A Visual Index enables the User to look at something on your product, identify it, and find where it is described in your document.
WIN. An acronym based on the words Wants Interests and Needs. A good User Document is written so the Users WIN. It's written based on the Users' Wants Interests and Needs. The other kinds of User Document (the ones that aren't so great) are product centered. These documents simply describe each of the products controls, features, etc and let the User figure out what to do with them.
Writing. (noun, not the act of writing, which would be a verb) Anything you have written on this project. It could refer to the document itself, a section of the document, or the material you wrote about a topic, sub-topic and so forth.
(c) 2006 Igetitnow! Training, Inc.