Software_Documentation_Notes

Document Sample
Software_Documentation_Notes Powered By Docstoc
					Software Documentation
Introduction
Documentation is a vital but often unappreciated part of almost every software product. Most software
documentation is written by technical writers, employees who specialize in the field. People not in the
field often fail to appreciate just how complex the process of writing documentation really is and how
dependent it is on developers and other software professionals. There's also a lot of confusion out there
about just what technical writing encompasses.

Lesson 1: What is technical writing?
The obvious answer to this question is any writing about technical subject matter, but that isn't the
correct answer. Another glib answer is the writing of computer manuals but that too isn't quite right
(although computer documentation is a very large subset of technical writing). I've seen the term
"technical writing" defined as "any writing designed to aid the reader in the completion of a specific task
or process". That too is correct but is so general as to be practically meaningless.

Technical writing is really a cross of all of these things: writing meant to convey technical knowledge and
how to apply it in specific situations to a very specific audience. In most cases that technical knowledge
is operation of a specific piece of computer software or hardware and that audience is the person trying
to use the same.

Types of documentation
Technical writers produce many different types of documents. The most visible documents are product
manuals, books that accompany products to customers and instruct them on product usage. Online help
consisting of a series of short instructional blurbs incorporated into the product itself is also common.
Some technical writers never write any product documentation meant for external eyes but rather write
product specification documents for internal use within the manufacturing company. Product
specification documents are used to formally define what a product will do, its external interfaces (for
instance, the type of menus and forms in the case of a graphical software application), and its internal
interfaces (the available modes of communication from one part of the product to another; the
functions front-end developers can use to access the underlying database in an application, for
instance). This course will concentrate on software product manuals and online help but the material
discussed will generally also apply to other documents created by technical writers.

The importance of audience
The audience is a key element that many people fail to consider. When your job is to convey knowledge
to someone, you need to understand what that person already knows and develop a sense of the
teaching methods likely to work for that person. If you're writing instructions for a customer service
representative don't assume they understand database theory or any of the associated terminology. It
sounds obvious, but the failure to properly analyze intended audience is the single largest pitfall facing
technical writers. Consequently, we'll devote an entire lesson to audience in this class.

The importance of word choice and consistent writing
A good technical writer not only understands his intended audience, he understands the importance of
clear and concise writing. Although most writers dream of beautiful prose that can move readers to
another plane of existence, technical writing is all about removing any possible ambiguities so the
reader understands precisely what to do. Short descriptive active sentences are generally better than
long flowery lines filled with metaphor. Word choice is paramount to a technical writer. If there is any
possible way an instruction can be misread or misconstrued someone will do so. When possible
consequences of wrong actions are data corruption and data loss it becomes very important that users
understand what you are telling them to do.

Consistency is also important. If you lead your users to expect all functions to appear in boldface
followed by a set of parentheses, then make sure all functions appear that way. Otherwise, your readers
may not realize that they're all functions and could get confused. Similarly, keep a similar style and
vocabulary throughout each document. If you're writing an introduction filled with very general and
basic conceptual material make sure you avoid as much technical terminology as possible and that you
always define all terminology you do use. If several writers are collaborating on the same document
make sure that individual voice doesn't shine through. When the document is finished you should not be
able to tell where one person stopped and another picked up. You shouldn't even be able to tell that
more than one person worked on the document.

The importance of organization
Technical writers tend to pay more attention to organization and the order material gets presented than
most other writers. In many cases, other writers have some leeway in presentation. More often than not
the material can be organized in several different ways and still retain its effectiveness. This is not often
true for technical writing. Since much of the time you're either providing instructions - by their very
nature a series of ordered steps - or providing background information that builds on prior material and
tasks already completed organization is extremely important. If you fail to give users an essential step of
any procedure they will not successfully complete that procedure. If you fail to discuss a basic topic
before moving on to a related advanced topic they most likely will get confused.

It's your job to analyze everything the user needs to do to successfully use a product and determine the
order they need to do those items. Then you need to determine what the user is likely to already know
and make sure that you provide every other scrap of needed information. In addition you must analyze
how someone who doesn't understand the product as well as you do would think about the product and
provide logical entry points to the necessary material given those expectations. It doesn't help to
provide every scrap of information your users need if they can't find that information within your
document.
The importance of indexing
Indexing is an important but often overlooked step in this process. Most users are going to either turn
directly to your table of contents or turn directly to your index and start looking for the material they
think they need. You need to make sure that information can be found from either method even if the
user doesn't yet know precise terminology or an exact word to look up. Cross-indexing is an art, one that
eludes many otherwise very competent technical writers. Indexing is a skill that needs to be developed
and practiced regularly.

The importance of editing and review
You might think the process of technical writing is complete once you put the last word on the page, but
it isn't. Every document needs to be reviewed and edited. In some cases you'll be fortunate enough to
have an actual editor in place to edit your document, but most technical writers must rely on another
technical writer or even do it themselves. In addition to the normal editing tasks of checking grammar,
general word usage, and spelling, technical editing includes several other elements including checks for
consistent word usage, checks that a consistent audience is maintained, and checks that the
organizational choices make sense.

Reviewing often occurs at the same time as the editing process but it serves a very different purpose.
While editing ensures a clean grammatically correct document with consistent style, it doesn't test the
accuracy of the content in any way. Reviewing does. If possible, you should have at least one of the
developers who wrote the product participate in a review as well as at least one person who fits the
target audience profile. If the person within the target audience doesn't understand everything you
wrote then even if it's accurate you haven't successfully met your mandate and need to re-write the
document accordingly. If the developer finds inaccuracies or points out areas where the product was
changed then similarly you need to fix those before declaring the document finished.

Lesson summary
As you can see, technical writing is a complex process that involves a lot more than simply sitting down
and putting pen to paper (or fingers to keyboard). The rest of this course will delve into many of the
areas discussed here in more detail. By the time we're finished you should have an excellent
understanding of the process from start to finish.
Lesson 2: The Importance of Audience
The audience is a key element that many people fail to consider. When your job is to convey knowledge
to someone, you need to understand what that person already knows and develop a sense of the
teaching methods likely to work for that person. If you're writing instructions for a customer service
representative don't assume they understand database theory or any of the associated terminology. It
sounds obvious, but the failure to properly analyze intended audience is the single largest pitfall facing
technical writers.

Examine the software to determine your user base
If you don't understand your audience then chances are you won't be able to write documentation
they'll understand. Evaluating your audience can be a difficult task but it is absolutely essential you do
so. The best way to start analyzing your audience is by evaluating the product you need to document.
You can tell quite a lot about your intended audience from the software since they are also the intended
users of the software.

If you're tasked with teaching developers how to write front ends for your product using Visual Basic,
then you already know quite a lot about your audience. You know:

       They are developers
       They know Visual Basic
       They are familiar with user interface design

In actuality, perhaps some of your readers will not fit this description, but it is your task to define the
supported skill set, make it clear to your readers what you expect them to already know, and then write
the book as if they know precisely that - no less and no more. If some of your readers do not meet all of
the prerequisites you've set out for your book then it is their responsibility to gain those skills before
attempting to use your book.

In some cases, your intended audience will not be so clearly defined. Parts of your book may include
overview information while other parts delve deep into the inner workings of your product. In these
cases you'll need to work particularly hard to develop a list of things and terminology all of your readers
will understand, and perhaps divide your book into several sections for analysis. Just be sure to clearly
state who each section is intended for within your introductory material.

Discuss the user base with the product manager
It's all well and good for you to determine just who your intended audience is, but if the majority of
people actually using the product differ greatly from your vision then you need to adjust your plans.
Another way to determine who will be using a particular product is to discuss how that product is being
marketed. The product manager is usually responsible for setting the requirements and marketing
direction for a product. He or she should be able to provide a 30,000 foot view of what the product does
and who should be using it. In general the product manager is in charge of the overall product that ships
to users including the documentation. Although the chain of command may vary from company to
company, you will most likely need the product manager to sign off on your documentation plans and
on your final manuals.

You may find that the product manager has a vastly different view of what the product does than you
do. Product managers usually work in the abstract; they'll look at product specifications and the
intended purpose of a product rather than what the developers actually made a product do when they
built it. If you've based your vision on a working version of the product and it differs greatly from that of
the product manager it is your responsibility to bring that discrepancy to his attention. Whenever
possible, you should point out these discrepancies between plans and implementation to the developers
and other interested parties as well as the product manager so that everyone understands precisely
what is it the shipping product does regardless of intentions. Unless directly ordered not to do so, you
should document what the product actually does rather than what it's supposed to do.

Applying your audience analysis to your writing
You should keep your view of the intended audience in mind at all times throughout your design and
writing stages. As you're writing, think about what someone with that skill set and experience would
already know about the topics you're writing about. Consider whether they'll be familiar with standard
terminology or if you need to define every technical term you use. Organize your book in a way that will
make sense to that audience. If you expect a particular book to be used as a reference, make sure each
small piece of information is indexed and otherwise easy to find. If you're writing a conceptual overview
of a topic, make sure either your intended audience should already know the topics leading up to that
one or that you've documented those other topics before this one.

Going back to our previous example of teaching Visual Basic developers how to build front end
applications to our product, we know we can insert Visual Basic code into our documentation without
much explanation, that we can assume the reader understands the concepts of data types, that the
reader knows what forms are and how to move from one form to another, that they know how to
create buttons, labels, and other controls, and that they understand how error handling works in Visual
Basic. However, if our product makes various error messages available, I cannot assume the user knows
these codes but I can assume they know how to implement them once I provide a list of codes and when
they should be used.

What happens if your audience analysis is wrong?
Many of you probably didn't understand what all of the Visual Basic terminology I used in the last
section means. That's because, most likely, you aren't Visual Basic developers. You weren't the intended
audience described in that example, so you didn't have to understand what I expected Visual Basic
programmers to understand.
However, since you are the intended audience for this class and knowledge of Visual Basic programming
is not a prerequisite, I should have defined those terms, or used more generic language to describe
similar concepts. Because I didn't I left many of you scratching your heads wondering what I was talking
about. This is bad.

Your initial audience evaluation may be wrong for a number of reasons or, as in the case of the example
above, there might be two audiences which have different backgrounds and knowledge bases. The best
you can do is clearly define an audience and clearly state, up front, who you are writing for. In some
cases, you may be given two audiences with very different requirements. For instance, you might be
told that in addition to teaching those Visual Basic programmers what they need to know to write those
front end applications, a particular chapter of your book will also be available as a sample to potential
customers so they can evaluate the quality of the documentation. In that case, you need to keep both
audiences in mind and, to some extent, write to the lowest common denominator.

Even if there's only one audience you can still make mistakes. You might not have understood what the
product does well enough to competently evaluate its intended audience. The product can change
significantly after your initial interaction with it. Sometimes the overall documentation plan changes and
you're stuck with a different focus than you were originally assigned. For instance, going back to our
example, although originally you were supposed to write separate guides for writing front end
applications in Visual Basic and in Java, the powers that be decided two months into your project to
combine the two books. You've already written half of the Visual Basic book assuming everyone who
reads it will know Visual Basic. Now it's your job to go back and determine what people who write front
end applications in either Visual Basic or Java have in common and which items you'll need to explain
better because only one group will recognize the terminology you used or because a specific concept
exists in Java but not Visual Basic.

Your conversations with the product manager, with other people working on other books for your
product (assuming there are others), with developers who are writing the software, and with testers and
other internal personnel trying to use the product will help you hone in on places where you don't write
to the correct audience. Hopefully all lapses or changes of focus will be caught before your manual is
actually read by real users.
Lesson 3: The Importance of Word Choice and Consistent Writing
A good technical writer not only understands his intended audience, he understands the importance of
clear and concise writing. Although most writers dream of beautiful prose that can move readers to
another plane of existence, technical writing is all about removing any possible ambiguities so the
reader understands precisely what to do. Short descriptive active sentences are generally better than
long flowery lines filled with metaphor. Word choice is paramount to a technical writer. If there is any
possible way an instruction can be misread or misconstrued someone will do so. When possible
consequences of wrong actions are data corruption and data loss it becomes very important that users
understand what you are telling them to do.

Consistency is also important. If you lead your users to expect all functions to appear in boldface
followed by a set of parentheses, then make sure all functions appear that way. Otherwise, your readers
may not realize that they're all functions and could get confused. Similarly, keep a similar style and
vocabulary throughout each document. If you're writing an introduction filled with very general and
basic conceptual material make sure you avoid as much technical terminology as possible and that you
always define all terminology you do use. If several writers are collaborating on the same document
make sure that individual voice doesn't shine through. When the document is finished you should not be
able to tell where one person stopped and another picked up. You shouldn't even be able to tell that
more than one person worked on the document.

Exercise proper word choice
I often find myself muttering the famous line from The Princess Bride as I read books: "I do not think
that word means what you think it means". Many writers have at least a minor problem with misused
homonyms - using "their" when they mean "they're" or using "it's" instead of "its". It's important to
have a good general grounding in language and grammar to avoid these errors.

There are a lot of other problematic words that sound similar but have very different meanings.
Selecting the incorrect one can really confuse your users.

These are common pitfalls that befall most writers. Beyond general proper word choice, technical
writers must be sure to develop a very precise vocabulary specific to the product or projects they're
working on. There are many terms and names that have commonly been adapted by the computer
industry; you must learn these conventions and use them properly so that readers can apply their
previous knowledge to your books. If a particular type of GUI screen element is typically called a widget
and you call it a whamboozle, not only do you not get instant recognition from people who know what a
widget is, you could lead them to believe your whamboozle is not a widget (for otherwise you surely
would have called it a widget).

Most of us are taught in school to look for alternate ways of saying the same thing when we write.
Unfortunately part of being a technical writer is unlearning habits our English teachers drilled into us for
years. Technical writing exists solely to convey information. It is not meant to be pretty writing, writing
that makes you sigh with pleasure just from the reading. It isn't generally meant to make the reader
think about a host of ideas, sorting through their own views on controversial or confusing topics. Many
of the constructs used in other types of writing simply aren't appropriate when you're writing
documentation. Remember all those lessons regarding metaphors and simile? Purge them from your
brain.

If you're writing for clarity above all else it is important to use the same terminology over and over
again. If you refer to a particular nameless part of your product as a wombeezil make sure you use that
term over and over again rather than trying to come up with fancy terms and descriptions solely for the
sake of adding variety to your writing.

There are entire books devoted to defining common computer terminology and common usage of
terminology in documentation; I cannot go into all of even the most common issues here. I strongly
recommend referring to the Microsoft Manual of Style for Technical Publications for more information
on this and other style concerns. Unfortunately, the book is currently out of print so you may have so
difficulty locating a copy.

Use short active sentences
Traditionally technical writers are told to always use short active sentences. This is good advice, but
writers today are generally granted a bit more leeway than those of twenty years ago. Short active
sentences still communicate instructions better than passive or long sentences - they leave less room for
ambiguity or misinterpretation. However, some passivity and longer sentences are generally allowed
within conceptual material (depending on your editor and group style rules).

In all cases, extraneous words should be removed. If your sentence makes sense without "the fact that"
then delete that phrase. Extra words just give people more ways to misconstrue your meaning.

Use a consistent voice
Voice in writing is a nebulous thing. It's difficult to quantify and can be even more difficult to control.
Voice is essentially the tone of the writing. Most educational books are very formal and dry, often
concerned with testing or expanding the vocabulary of those reading. Most fiction tries to be true to one
character, picking up his or her mannerisms and attitudes and showing them on paper.

There is no one proper tone for documentation beyond the need for consistency. Readers may not
specifically think about voice, but a sudden change from friendly to terse will be noticed and detract
from the reader's ability to focus on the information provided.

Many people feel a dry academic style works best while others prefer to be friendly and use simple
language. Some types of documentation are best suited for a specific tone - introductory material
generally works best with friendly inviting language and reference material is more geared toward short,
terse language - but in general it doesn't matter what voice you use as long as it's consistent.
Develop a consistent style
A lot of different elements combine to define a style for your writing. In general terms a writer's style
encompasses things like voice, word choice, the use of formatting, and other similar elements. It's the
overall package, if you will.

When technical writers discuss style they generally concentrate on word choice and on the formatting
and presentation of material - how different product elements are capitalized and typeset, how chapters
are paginated, how indexes are formatted, and similar concerns. Most writing groups have their own
style guides that cover that departments views on the spelling of certain ambiguous words (email vs. e-
mail, for example). Often they select a particular book then add or change specific elements to suit their
needs. The Microsoft Manual of Style for Technical Publications is the most popular choice, for good
reason. It's the most comprehensive guide I've seen. By starting with this (or another) book and just
modifying its rules to suit your needs, technical writing departments can save a great deal of time and
effort.

These customized sections (or full, independent style guides) should contain lists of product-specific
words and their acceptable usage as well as departmental rules for comma usage, preferred choice
when there are two acceptable spellings of a word, and your choices for capitalization, bolding, and
italicizing. This last part is particularly important when documenting a programming language or tool -
there are so many different elements in a language and your readers need to know, at a glance, whether
you are discussing a function or a query (for example).

If you're writing alone, you probably don't need a formal style guide as long as you can be consistent. If
you find yourself wavering, or if during the editing process you notice a lot of variation in word choice or
formatting, then take the time to write a short personal style guide. Make sure you actually refer to it
when writing - its mere existence will not add consistency to your writing.

Style guides and issues related to style can be among the most divisive in any writing group. Everyone
has their own ideas on what is proper and right, and often those ideas conflict with each other. It's
almost certain that in any group situation you won't like all of the decisions, but it's important that you
abide by them.

Maintain consistency in collaborative projects
It is especially important to maintain a consistent voice and style when more than one writer works on a
single document. Readers should not be able to tell which parts of a book are written by one writer and
which by another, or even that more than one writer worked on the book.

Minor deviations from the accepted style may not be noticeable in a book written by one person (as
long as they are consistent) but if two or three different people each differ from the standard in
different ways it will be noticeable and distracting to the reader.
One way to avoid such problems is to require each writer to read and edit those chapters or sections
written by the other writers. If one of the other writers does something consistently different from the
way you do it, it should be very easy to spot. Once these problem areas are identified you as a group can
determine the best way to fix them and provide the needed consistency.
Lesson 4: Writing Procedures
Most technical writers spend at least part of their time writing procedures. Procedures are essentially
detailed instructions for performing one or more tasks. Unless your documentation is strictly conceptual
(explaining a topic rather than telling your readers how to use the software), you will need to write
procedures. Since readers will be following your instructions on real applications with real data, it is
particularly important that your directions be clear, concise, accurate, and easy to follow.

Use active language
A procedure tells your reader to perform a specific action or set of actions. Good instructions use active
language, commanding the reader to act rather than discussing actions that have been taken or could be
taken by others. There's a big difference between saying "the dropdown box in the corner of the page
can be used to select the date" and "select a date using the dropdown box in the corner". The first
informs your reader what that particular dropdown box does and the second tells them to do it. The text
introducing a procedure can discuss when to perform the procedure; the procedure itself needs to tell
the user how to do the needed actions and assume that they are, in fact, doing them.

Use short phrases and sentences
It's important to give each instruction as clearly as possible. The fewer words used to convey a particular
task, the less places there are for a user to get confused. Anyplace you can use a single word to convey
an action, do so.

Avoid any elaboration or explanation within the procedure itself. If you need to provide options or
explain why a particular task is important, do it in paragraph form before you begin the procedure. If the
user can choose more than one way to perform a specific task, present each procedure separately after
explanatory text discussing when that particular option is a good choice.

Use ordered lists
By definition a procedure consists of a set of tasks that need to be performed in a specific order. By
presenting these tasks in an ordered list, with steps 1, 2, 3, etc., you reinforce the need to follow a set
order. Numbered lists have an ingrained implied order that's almost subconscious and thus provide
much stronger impetus that simply supplying paragraphs filled with "Do this then do that" terminology.

Ordered lists also help you bone down the language to its simplest, and thus clearest, form. By removing
all of the extraneous connective words needed to indicate order in paragraph form you remove verbiage
that could confuse your readers.

Provide one instruction per step
One of the common mistakes people make when writing procedures is trying to stuff several steps into
one line. They think that each instruction is simple so they can safely combine a few easy directions into
one combined step. Unfortunately no matter how simple those individual instructions are, any step that
tells you how to do more than one thing is potentially confusing. Avoid that confusion by limiting each
step to one instruction no matter how simple or mundane.
For instance, when telling users how to create a new account you could say:

    1. Enter the desired username and password into the appropriate fields
    2. Select the desired permissions for the new user
    3. Hit enter to add the user

but this is clearer:

    1.   Enter the desired username in the username field
    2.   Enter the desired password in the password field
    3.   Select the Read checkbox if this user has read privileges
    4.   Select the Write checkbox if this user has write privileges
    5.   Select the Exec checkbox if this user has execute privileges
    6.   Hit enter to add the user

Be consistent
Consistency is important in all documentation, but especially so when writing procedures. In particular,
it is paramount to use consistent names for screen elements like buttons, forms, tabs, and windows.
Many of these elements won't be named within the software so you'll have to name them. Choose a
logical name that makes it obvious what particular element you're referring to and then propagate that
name throughout the entire documentation set.

Collect all of the names you create and make sure they're added to a common database of product
terminology. In an ideal world, these terms would be added to a group style guide or glossary, but even
if you don't do that, make sure they are preserved and available to everyone working on that product.

Don't feel like you need to come up with ten creative ways to tell people how to press a button. Tell
them to press the button (or tap it, or choose it, or whatever terminology you've decided on) each and
every time. You shouldn't break out the thesaurus, but rather use repetitiveness to really pound home
clarity.

In addition to consistent use of names and terminology in general, it's also important to use parallel
constructs within your procedures. The human brain looks for parallelism and is bothered when it's not
there (even if it doesn't completely understand what's wrong with a particular sentence). By beginning
each step with a similar phrase and tone, you're allowing the user to ignore the writing and concentrate
on the content.

Perform the acts you're describing
A sure way to provide incorrect instructions is to rely on your memory when writing procedures. Even if
you've performed a task hundreds of times, you will always forget one small step or provide wishy-
washy directions at some point along the way because you can't quite remember if the menu item is
named "Remove all users" or "Delete users".
If you're overly familiar with a procedure you are also prone to leave out steps or combine multiple
steps into one gigantic step that's confusing to someone not as familiar with the process as you are.

For instance, most of us know how to save a file. Let's assume you're all using Mac OS X Jaguar writing in
TextEdit (since that's precisely what I'm doing right now and I always heed my own advice of doing what
I'm describing). I could assume you understand the basic idea of how to save a file and provide this
procedure for saving files:

    1. Save the text file in the location of your choice

But in reality what I want you to do is:

    1.   Select the File|Save As menu item
    2.   Name the file in the Save As text area
    3.   Select a location from the Where dropdown box
    4.   Press the Save button

or alternately:

    1.   Select the File|Save As menu item
    2.   Name the file in the Save As text area
    3.   Navigate to the location of your choice using the directory viewer
    4.   Press the Save button

Now most of that should be self-explanatory, even if you've never saved a file in Jaguar before. But
people learn and extrapolate at different rates and by spelling out precise directions I've made sure
every reader will be able to follow my instructions quickly and without much experimentation.

Lesson Summary
There's no question that the ability to write clear and correct procedures is absolutely paramount for
anyone writing software documentation. It's also true that there are a lot of rules. The good news is that
most of us have a lot of practice with procedures. We may not call them procedures, but we encounter
sets of instructions all of the time in daily life in everything from recipes when we cook to driving
directions when we travel. Thus we all have an inborn recognition of procedures and an inherent
understanding of how they work. You just need to add common sense and good writing skills to that
understanding and you'll be able to write your own clear and easy to follow procedures.
Lesson 5: Using Tables and Graphics
As a technical writer your job is to convey information to your readers. Sometimes the best way to do
that is by writing long descriptive passages. Sometimes the best way to do that is by providing short,
easy to use procedures detailing precisely how to perform important tasks. But sometimes you need to
provide a screenshot or a graphical representation of an idea before it can really gel for your readers.
Part of your job is judging when to rely solely on words and when to provide a graphical illustration of
the information you need to impart to the reader.

Using tables
Many people today think of tables as layout tools, tools to help present information in pretty columns.
Although tables are often misused in this fashion, they are not meant to be an underlying layout tool.
Rather, their purpose is to present tabular data clearly and understandably.

What is tabular data? Tabular data is any collection of data that most logically fits into a matrix. This is
most often a series of elements which each have multiple properties. For instance, you could have a
series of error codes and their corresponding text messages. You could present these as a list, but if you
present them in a table you don't need as many descriptive words and the two parts of each error - the
code and the message - are visually separated and easy to identify at a glance.

To illustrate this example, let's display a list of errors and then a table containing the same information.
First the list:

       Error 190 occurs when you run out of memory
       Error 200 occurs when your input value falls out of the allowed range
       Error 300 occurs when you cannot connect to the database

And now the table:

                  Error Code                           Error Message
                  190                                  Out of Memory
                  200                                  Out of Range
                  300                                  Connection Error
As you can see the table is a lot easier to parse. Imagine if each of the elements in the collection had
four or five different properties. In this example, the errors could also be categorized by error type and
you could also note whether the error message can be localized. The list would get a lot more dense
and complicated, while the table would remain relatively easy to read:

       Error 190 occurs when you run out of memory. It's a basic system error that can be localized.
       Error 200 occurs when your input value falls out of the allowed range. It's a parameter error that
        cannot be localized.
         Error 300 occurs when you cannot connect to the database. It's a basic system error that cannot
          be localized.

or within the table:

Error Code                  Error Message             Error Group                Can Be Localized?
190                         Out of Memory             System                     Yes
200                         Out of Range              Parameter                  No
300                         Connection Error          System                     No
As you can see, tables really do make a big different. Use them judiciously, but use them whenever you
need to present a collection of tabular data.

Using screenshots
Sometimes a picture really is worth a thousand words. No matter how well you describe the user
interface of a product, there's really no replacement for showing your users what it actually looks like.
You need to describe things too - screenshots aren't a replacement for proper discussion - but
sometimes an illustration can help your text make more sense.

As with tables, you don't want to overuse screenshots. If an entire section is devoted to the same tab of
your application, you generally don't need to present a visual image of that tab every time you ask your
users to do something within that tab. If you present the same picture six times within a single
procedure it merely serves to slow down the process, spread the information out over multiple pages,
and interrupt their train of thought.

In general unless they are small graphical representations of buttons or active screen elements, it's best
not to include any screenshots or other illustrations within a procedure. Provide any necessary graphics
before you get into the procedure so your users can refer to them as needed without having them
interrupt the procedure itself.

Using representational drawings
Just as screenshots can help your users better understand procedures and how to navigate through the
user interface of the product you're documenting, representational drawings can help them understand
conceptual material. Spending three pages describing the product architecture in detail is all well and
good, but without a diagram showing how your application server sits above the database but behind
the web server even a lengthy description may not register with your users.

Again, as with screenshots, representational drawings cannot take the place of the actual written
discussion. Without text to frame the drawing your users won't know what they're looking at or why
they should care. You need both elements working in concert.
Writing captions
Although not absolutely necessary, most product manuals provide captions for all graphics including
drawings, screenshots, and tables. These captions provide a short catch-phrase that tells your users
what they'll be seeing in the graphic. It's sort of an extra reminder of what they should be thinking
about when they look at the table or picture.

Captions tend to stand out more than the general text surrounding the graphic so you can find a little bit
of information about a graphic without having to scrounge around the nearby text. If you've arrived at
the page to see that particular table or figure rather than to read the section of text, this can be a real
timesaver.

Table of Figures and Table of Tables
Most books provide a Table of Contents to help readers understand what material is covered within the
book and to help them quickly go directly to a specific piece of information they need. Many manuals
also provide Tables of Figures and Tables of Tables for the same reason.

Usually found immediately after the Table of Contents, these two listings generally list the figures -
screenshots and representational drawings - and the tables within the book using their captions as
descriptors. These tables are not as widely used by readers as the Table of Contents or the index, but
they do provide an alternate route to quickly find specific information throughout the book.

They also give the reader a sense of which concepts are most important in a book. Because the Table of
Contents lists everything within a book, it doesn't give you any sense of what the key areas are. It's all
listed and treated equally. But if a concept is important enough to warrant a representational drawing
the reader knows it's something you particularly want them to understand well.

Lesson Summary
Graphics - screenshots, representational drawings, and tables - are an important part of technical
writing. The key is to use them appropriately. Determine when they are needed and when they aren't.
Make sure they fit the topic you're discussing and that you provide a short but informative caption for
each graphic. Most importantly, make sure that you don't add graphics just for the sake of having pretty
pictures in your book.
Lesson 6: Indexing Your Documents
It's your job to analyze everything the user needs to do to successfully use a product and determine the
order they need to do those items. Then you need to determine what the user is likely to already know
and make sure that you provide every other scrap of needed information. In addition you must analyze
how someone who doesn't understand the product as well as you do would think about the product and
provide logical entry points to the necessary material given those expectations. It doesn't help to
provide every scrap of information your users need if they can't find that information within your
document.

Indexing is an important but often overlooked step in this process. Most users are going to either turn
directly to your table of contents or turn directly to your index and start looking for the material they
think they need. You need to make sure that information can be found from either method even if the
user doesn't yet know precise terminology or an exact word to look up. Cross-indexing is an art, one
that eludes many otherwise very competent technical writers. Indexing is a skill that needs to be
developed and practiced regularly.

Deciding what to index
It can be very difficult to decide which words to index. You don't want or need to build a complete
listing of every word in your manual yet at the same time you want to make all of the important
information within easy to find for every person reading the book.

A good place to start is with section headings. If an idea is important enough to merit a section heading
it's probably important enough to merit an index entry. A chapter discussing building clients in Visual
Basic might cover topics such as the available objects, error handling, and debugging. The first pass at
indexing that chapter might include the following entries:

       Debugging in Visual Basic
       Developing Visual Basic Clients
       Error Handling in Visual Basic
       Objects in Visual Basic
       Visual Basic Clients

That's certainly a start, but those five entries aren't going to effectively lead people to everything they
need to know about developing client applications in Visual Basic. That will probably be enough to lead
any user to the general section on Visual Basic, but a user looking for information on a particular object
may not think to look under Visual Basic. After integrating major headings, the next step is to look at
the information covered by each and determine which pieces of information users are most likely to
specifically seek out by name.

Most likely users will want specific information on individual objects. If the chapter discusses four
objects - OurFactory, OurBean, OurStream, and OurText - then those should each be indexed as well.
Basically during the indexing process you should return to your audience analysis and really think about
what users will want to do with the information you provide and the background they bring to the table
that will lead to the terminology they use to look for that information.

Choosing which instances to mark
The words "error handling" might appear three times in every paragraph within the error handling
section. You don't want to include separate index entries for each instance - that would be overkill and
lead to a cluttered, difficult-to-use index. If your indexing supports page ranges, you could decide to
include the entire range of the chapter within a single index entry. If your index only allows single page
entries, then you'll need to determine if marking the first page of the section is sufficient or if you need
further markers at important points within the section.

Perhaps a more complex situation is when you discuss a concept in a chapter overview and then provide
full details a page or two later within the chapter. You'll need to decide whether it makes sense to index
either places or just the area where you provide the detail. This is your choice, and you'll need to decide
what makes sense for your book.

Build in redundancy
Once you've chosen the topics and terms to index, you might think you're almost done with your index.
You would be wrong. Not every reader thinks the same way and simply including a single entry for an
importance concept isn't enough. If there are alternate terms use them.

For instance, in our Visual Basic chapter above, include the common abbreviation for Visual Basic - VB -
in the index. Think of alternate terminology people might use when saying "developing clients" and
provide index entries for them. Do the same for other words and phrases. If you don't use that
terminology at all within the book, use a "see" reference to indicate that it's covered under another
name.

We came up with five base index entries for the Visual Basic chapter above. Adding in redundant and
alternate entries, we might get the following entries:

       Building Visual Basic Clients
       Clients, Visual Basic
       Clients, Visual Basic, Available Objects
       Clients, Visual Basic, Debugging
       Clients, Visual Basic, Error Handling
       Debugging, Visual Basic
       Developing Visual Basic Clients
       Error Handling, Visual Basic
       Exceptions: see Error Handling
       Objects, Visual Basic
       Throwing Exceptions: see Error Handling
       VB Clients: see Visual Basic Clients
       Visual Basic, Available Objects
       Visual Basic, Debugging
       Visual Basic, Error Handling
       Visual Basic Clients

As you can see, this gives the user many more ways to find that same information they need.

Consistency in Indexes
Just as it's important to be consistent throughout the text of the manual, it's also important to provide
consistent index entries. If you normally capitalize all words in an index entry, make sure you capitalize
them in every single entry. If you generally include three variants on each object, make sure each
variant is included for each object.

You'll also want to be consistent regarding which occurrences of a word or phrase to include in the
index. If your chapter has a general overview that briefly discusses each major topic then later sections
on that discuss those topics in detail, either index both locations for every term or don't index both for
every term. Don't index some of the words in the overview and some just in the detailed sections that
follow.

When to build your index
Many people recommend doing all of your indexing at the end of the writing process. This is a holdover
from the time when indexing had to be done by hand and the simple shift of a single page could
invalidate most of your work to date. In these days of automatic indexing and markers that move with
words as they shift locations there really is no technical reason to index at the end of the process and
many people choose to index as they write.

There are advantages and disadvantages to either choice. Indexing as you go definitely slows down the
writing process, meaning it will take longer before you're reading for editing and review. Many people
find the resulting stop and go writing process prevents them from properly concentrating on what
they're writing and thus won't index as they go. If you index at the end of a tight schedule, you can do
your indexing while others are editing and reviewing your book, then give the editors your index once
they hand back the rest of your book.

Leaving the indexing to the end of the writing process can lead to a very rushed and often inferior
product. Most non-writers fail to understand the importance of a good index and it's more difficult to
get a product manager to give you more time to index a book than it is to get more time to write the last
two chapters. On the other hand, indexing as you go is more likely to lead to inconsistencies as you
could make different choices regarding capitalization or marker placement or other index features
during different phases of the indexing. These problems should be caught during the editing process. If
you index as you go, be sure that someone edits the final result with an eye toward consistency.

Another alternative is to index each chapter or major section after it's finished. This allows you to write
major chunks of text without constant interruption and still avoids the rush of trying to fully index a
book when time is running out. It can still lead to some consistency problems, but again these should be
caught during the editing process.
Lesson 7: Editing And Reviews
You might think the process of technical writing is complete once you put the last word on the page, but
it isn't. Every document needs to be reviewed and edited. In some cases you'll be fortunate enough to
have an actual editor in place to edit your document, but most technical writers must rely on another
technical writer or even do it themselves. In addition to the normal editing tasks of checking grammar,
general word usage, and spelling, technical editing includes several other elements including checks for
consistent word usage, checks that a consistent audience is maintained, and checks that the
organizational choices make sense.

Reviewing often occurs at the same time as the editing process but it serves a very different purpose.
While editing ensures a clean grammatically correct document with consistent style, it doesn't test the
accuracy of the content in any way. Reviewing does. If possible, you should have at least one of the
developers who wrote the product participate in a review as well as at least one person who fits the
target audience profile. If the person within the target audience doesn't understand everything you
wrote then even if it's accurate you haven't successfully met your mandate and need to re-write the
document accordingly. If the developer finds inaccuracies or points out areas where the product was
changed then similarly you need to fix those before declaring the document finished.

Working with an editor
If you work in a large organization chances are you'll have one or two editors who need to sign off on
your documentation before it’s published. These editors check your books for spelling mistakes,
incorrect grammar, flow, and other general common writing problems. They also check for proper use
of trademarks, adherence to the corporate style, consistency, widow and orphan lines, pagination
issues, and other features that might be specific to your particular company or department.

You might think proper grammar provides a concrete set of rules that leave no room for interpretation
but that's not the case. The hardest part of working with different editors is that each has his or her
own slightly different interpretation of the rules. The rules regarding commas, for instance, are flexible.
I've worked with editors who saw commas as the enemy and eliminated as many as humanly possible
without altering meaning and I've worked with people who prefer to include commas every single
instance it's possible to do so. Both are correct - it's all a matter of preferred style. Until you learn the
style of a new editor expect some growing pains.

The single most important thing to remember when working with editors is that they do not, in general,
understand the subject matter of the books they're editing. They do, at times, unwittingly suggest
changes that alter your meaning. It is your responsibility to go back to the editor and point this out. Just
because an editor requested a specific change does not automatically mean you must make it. If it's a
bad change in your opinion, discuss it with the editor and explain why you feel your way is better. Any
editor worth their salt will sacrifice their rules or strictly correct grammar for accuracy.
Peer editing
Smaller groups often don't have any editors but rather institute peer editing. Once your book is finished
(or once specific sections are finished) you give them to another writer in the group for critique. Again,
the main purpose is to ensure correct spelling, correct grammar, and adherence to the group style. In
some cases the writer editing your work will know nothing about its subject but in others the writer may
indeed know the product quite well. In those cases, you'll most likely get comments on the content in
addition to actual editing. This amounts to an extra reviewer and content-related comments should be
treated as review feedback.

Peer editing is usually an informal process leaving you the option to integrate or ignore the results as
you see fit. It's less like to catch small errors or minor deviations from the accepted style than a formal
edit. Writers have varying experience with editing and sometimes the best writers are not the best
editors. If you work in a group for a long time you'll get a feel for who the better editors are and,
hopefully, be able to give them your books for editing.

Self editing
If you work alone, work as a contractor, or sometimes if you're in a small group there isn't anyone else
available to edit your work so you have to do it yourself. Editing your own work is very difficult because
you know what you're trying to say. You have extra context clues and background to fill in any blanks
that might actually be in the writing so it's easy to miss mistakes or omissions.

If at all possible, leave a little time between the completion of the writing and the beginning of your
editing process. This gives your brain some time to forget exact word patterns and helps you catch
more problems with the writing. If you can, it's best to work on another project in between the writing
and editing steps.

Reading your work out loud can be a very effective self-editing tool. Your brain is less likely to fill in
missing words if you're trying to vocalize them. Any awkwardness or odd pauses in the writing are also
more apparent when read out loud.

Why reviews are important
Technical writers get their information in a number of different ways. Many software products are
described in specification documents well before their first line of code is written. These documents
serve as a starting point for everyone working on the product - developers, technical writers, and testers
alike. Often cross-functional teams have ongoing meetings to access progress and discuss changes to
the product. Developers, product managers, and other involved parties send emails back and forth
containing product information and suggestions.

As a technical writer it's your job to be a fly on the wall at as many of these conversations as possible.
Get yourself on every email list you can. Get invited to those boring meetings. If you're lucky, you can
also be an early alpha or beta tester of the product and see how it works first hand.
Even if you get a constant stream of emails, go to three meetings every week, and get the chance to use
the product to your heart's content, there will be last minute changes to the product. There may be
earlier changes that you don't know about or that never came up in any of the meetings. Some
developers may not be forthcoming with changes or your product manager may forget that you need to
know a particular piece of information. Even if you have all of the information, you may have
misinterpreted something or not fully understood everything you read or heard. The review process is a
check built into the documentation process to catch all of those omissions and changes and mistakes.

Dealing with difficult reviewers
Some people are more cooperative than others. It's a fact of life. As a technical writer you need to deal
with a lot of people who don't necessarily see helping you as part of their job description (even when it
should be). Some people will be very forthcoming when you ask them questions, others will practically
need to be tied down before they answer you. Similarly when sending material for review, some people
will comply and give you the necessary feedback in a timely manner while others won't.

If a particular developer isn't cooperating with a review request, notify your manager and ask for his or
her help. They may suggest you discuss the obstruction with the reviewer's boss or have other
suggestions to elicit cooperation. If you can, find an alternate source of information - if a developer isn't
cooperating perhaps the person testing those features or a consultant using them will.

Ultimately as long as you tried to get your material reviewed, it's not your fault if there are technical
inaccuracies. Unfortunately this doesn't help the customers getting confused by the mistakes so you
should make every effort to get the needed feedback.

Integrating review comments
At the end of a review cycle you'll most likely have several sets of feedback on the same material.
Sometimes the comments will conflict, sometimes they may not make sense. More often than you'd
like they'll point out deficiencies and missing information. You can also get off the wall review
comments or run into a reviewer who feels it important to correct the grammar and writing style of your
book, often doing so without checking the technical content. As with the editing process, when it gets
right down to it, you are in charge of the document and you decide which comments are helpful and
need to be addressed in the documentation before it's released.

Corrections can generally be made within a few days, barring long discussion of conflicting comments,
but vital information that simply isn't documented cannot usually be added so quickly. If your release
date is nearing and a reviewer insists that a new chapter is needed, you may not have time to research
and write this new information. At that point it's your responsibility to inform the product manager of
the request to add more information and explain that it cannot be completed within the current
schedule. He or she can then determine whether the projected completion date is strict or if you can
have more time to add new information. It is unlikely that the product release date will be altered just
so you can add more documentation (although it has happened to me twice) so this determination will
generally be based on the current state of the product itself.
If you make extensive changes after the first round of reviews, you may want to ask for another round of
feedback from your reviewers. At the very least, you should send the changed sections to the reviewers
who suggested the changes so they can sign off on the modified information.

Which comes first - Reviewing or Editing?
In general, editors like to be the last person to see a book before it's released. If you have actual editors
chances are you'll want to go through the review process before the editing process.

Alternately, if you're fairly confident that there won't be massive changes needed after the review, you
could propose simultaneous review and edit periods. You could then offer the finalized, post-review
document to the editors for a brief final edit to ensure you didn't violate standards when you integrated
the review comments if that would make them more comfortable.
Lesson 8: The Tools of the Trade
Although there are a wide variety of tools you can use to create documentation, most writers use a few
core applications for most of their work. Some documentation is written in Microsoft Word and some in
other word processors, but most technical writers use Adobe FrameMaker to write printed books. Tools
like Quadralay WebWorks and Adobe Acrobat can take that FrameMaker output and generate HTML
and PDF files for end users and professional printers. Online help can also be written using a variety of
tools but most technical writers use RoboHelp.

This lesson isn't going to make you an expert in any of these products or even give you a sense of their
power and versatility. But it will give you a taste for each of the popular tools and why they're helpful
when writing software documentation.

Why not Microsoft Word?
Most people use Microsoft Word for the majority of their word processing needs. It's perhaps the most
pervasively used product on the market. A lot of people want to know why they can't just keep using
Word when they start writing documentation. The short answer is that you can but you probably
shouldn't.

There are plenty of technical writers who do use Microsoft Word to write documentation. It has enough
rudimentary word processing features to permit effective output of short documents and can generally
be massaged into handling mid-sized or even long documents to some extent. But it lacks many of the
features of FrameMaker that make it a more powerful option. For one thing, Microsoft Word doesn't
have any concept of books. You just have one or more documents that, as far as Word is concerned, are
independent files. You are responsible for maintaining consistency among the table of contents and
index. You are responsible for making sure all of the files are kept together, maintain a common style
and format, and fit into a single book. Word also provides very limited control over layout and style. For
the most part, all files created in Word look the same. It's very difficult to personalize and give your
documents a specific corporate look and feel.

What FrameMaker offers that Word doesn't
FrameMaker is designed from start to finish as a tool for creating books. It understands the book as an
object and that every book contains a subset of lesser elements like a table of contents, chapters, an
index, sections, illustrations, and others. It gives you the control to organize your book in a sensible
order, adding and reordering files at will, without the need to figure out which order to place files each
time you work with the book.

FrameMaker has the concept of a cross reference, sort of like a hyperlink, that lets you pull chapter and
page citations (or even paragraphs or sentences) from one place in the book and reference or include
them in another. These cross references are then automatically maintained - if the original text changes
its location or content the appropriate changes are automatically made in all references.
One of the main advantages to FrameMaker is the level of control it gives you over the appearance of
your book. I mentioned above that one Microsoft Word files end up looking pretty much the same as all
other Word files. With FrameMaker you can control exact layout of every type of page element. You
basically start with a blank page and can determine exactly how your book will look from there.

In actuality most Frame users do not ever see that blank page - someone has already made all of the
difficult choices for them and created a template to make it easy to implement the desired look.
Although Microsoft Word does have a concept of templates they are very basic. FrameMaker templates
capture every nuance of appearance and available formatting making consistency much easier.

Generating paper documentation
Once you've finished writing your book you still need to get them to your customers. Books can be
distributed as traditional paper books or in various electronic formats, most notably in either PDF or
HTML. Since your book exists only in FrameMaker at this stage, you'll need to convert it to these other
formats.

Paper books are generally sent to a professional printer for mass production and binding. Almost all
printers request high-quality PDF files from writers. You can use a full version of Adobe Acrobat (as
opposed to the more common Adobe Acrobat Reader) to create PDF files from FrameMaker. Adobe
makes this conversion very easy - as simple as selecting a new printer and printing the file with the
"Save as File" option checked (this can also be done using "Save as PDF" although in some cases this
doesn't work as well).

However, most printers require certain settings to be used while generating the PDF files. You'll need to
check with your printer and get a list of settings they want you to use - each printer varies slightly.
These settings can be changed in the Adobe Acrobat Distiller portion of Acrobat. Once you've done this,
creating PDF files for printing returns to the simple process of printing the Frame file.

Generating electronic documentation
HTML and PDF are the two most common formats used for electronic documentation. Although you can
distribute PDF files meant for printers electronically, most people choose to make hyperlinks active and
add a table of contents to the PDF file first. This involves a few changes to the Distiller settings and
some minor editing to the resulting PDF files.

The last few versions of FrameMaker have included a "Save as HTML" option but frankly it's not yet up
to snuff. The generated HTML has a lot of problems and needs quite a bit of editing before it looks nice
enough to send to customers. While this quick and dirty HTML generation is wonderful for internal
reviews and beta testing, most people choose to use Quadralay WebWorks to generate HTML for actual
release to customers.

Quadralay isn't perfect either, but it's a more robust option than the simple FrameMaker HTML
conversion. Quadralay works by mapping available page elements - headings, tables, footers, code
samples, and the like - to an appropriate HTML tag. For instance, first level headings in your Frame files
will generally be placed between <H1> tags in the resulting HTML. Not all mappings are so obvious, and
Quadralay lets you choose exactly how each element is converted. You could, for instance, choose to
start a new page for each first level heading rather than assign them as <H1>. Quadralay also
automatically generates next and previous links for each page as well as a table of contents.

The Great Tool Search
Just because something is the most popular tool used by technical writers doesn't mean it's the best tool
for you to use. Look around and see what the options are. Try a few out, if possible, then choose the
one that's right for you.

There's more to life than just writing - from time to time almost all technical writers need to create
technical diagrams, take screen shots, edit HTML files, and do other tasks beyond strictly putting words
on the page. Each of these tasks will involve using other tools and sometimes finding simple, easy-to-
use tools for these secondary tasks can save an enormous amount of time.

Part of being a technical writer is keeping up with trends and with the tools of the trade. The tools
discussed in this lesson will provide a nice starting point, but ultimately you'll need to form your own
collection of applications needed to get your job done.

Class Summary - What should you take away from this class?
This has been a densely packed class filled with a lot of information. This summary will reinforce the
most important points to take away from the experience.

Software documentation has a lot of elements. You can't just sit down and start randomly writing about
the product you're documenting then stop when you think you're done.

You need to analyze your readership and keep their needs, background, and experience in mind as you
plan and write your documentation. You need to carefully choose wording and always write as clearly
as possible. You need to understand when to include a figure or table and when it's best to present
information strictly textually. You also need to understand your book and your audience well enough to
effectively index the subject matter.

You need to respect style guides and formatting decisions made by others you work with even if you
don't agree with all of those decisions. You need to forge a good working relationship with developers,
testers, and other software professionals. You need to accept feedback and accept that the product
you're documenting will change. Most of all, you need to enjoy using software and teaching how to use
it to others.

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:11
posted:10/28/2011
language:English
pages:27