EDITING YOUR OUN DOCUMENTATION

Editing Your Own Documentation
Technical writers sometimes fall into the trap of thinking that the user is stupid. I have often heard technical writers say things like "well, if the user can't figure that out, maybe he’s in the wrong job!"
It is my opinion that users should not have to figure anything out. They do not read our documentation for fun, or to expand their minds, or to improve their ability to think. In fact, users would much rather not read our documentation at all. Technical documentation is usually nothing more than a necessary evil, something that users want to get through as quickly and as painlessly as possible. Our job is to make the documentation easy and painless to read. It should never cause a moment's puzzlement, stress, worry, or annoyance. The user should never have to say "huh?"
The main cause of user incomprehension is careless writing. While you may believe that this point is obvious, in fact, I regularly see user guides that contain spelling, grammatical, and punctuation errors, leaps of logic, ambiguities, missing words, and incorrect vocabulary, as well as such peculiar formatting as to make navigation difficult. Even the best writers make these mistakes at times.
While it is better to have someone else review and edit your documents, you can successfully eliminate many problems (all of which are described in more detail in other articles in this site) commonly found in technical documents by following the list below.
In the electronic version of the document:
Perform a spell-check on the document.
Search the document for the following usage infractions:
passive voice (search for is, are, were, by, etc.); replace with the active voice
future tense (search for will); replace with the present tense
conditional tense (search for ould); replace with the present tense
contractions (search for n't and 've); replace with full words
non-parallel construction (search for bulleted lists); ensure that the first word of each list item is of the same type (noun, verb)
unclear antecedent (search for "This"); ensure that "This" is followed by a noun and not a verb
and/or; replace with ". . . or . . ., or both"
forbidden words (search for "kill," "abort," and any other words that your company has deemed inappropriate or inexact)
Search the document for broken links.
Perform another spell-check.
After you have completed the steps above, print the document and look for any obvious problems in the following:
headers and footers (incorrect position of elements, incorrect text)
headings (inconsistent capitalization, improper hierarchy)
pagination (incorrect position of page number, chapters beginning on a left-hand page, Roman numerals where there should be Arabic numerals and vice versa)
TOC (incorrect alignment, tab positions, and hierarchy)
table format (improper page breaks, poor alignment)
Finally, read through the entire document while imagining that you are an inexperienced user; rewrite anything that could be misunderstood.

THE TECHNICAL WRITING PROCESS

The Technical Writing Process
The technical writing process consists of four phases:
planning
writing
delivery
archiving
The phases of the technical writing process
window.google_render_ad();
are not necessarily discrete. You might start the writing phase before you complete the planning stage, for example, or you might have to deliver the documentation before you feel it is finished. It is highly unlikely, however, that you will ever archive the documentation before you deliver it!
Some products are released several times. In this situation, you might be in the delivery phase of the first iteration of the project while you are in the planning phase of the second iteration. Don't panic: overlap in the technical writing process is quite normal.
Every project is different. The process described here might not exactly describe your situation, but it will be pretty close.
Managing Your Documentation Projects by JoAnn Hackos, provides more detailed information about the technical writing process.
The Planning Phase
Gather existing information—any or all of:
requirement specifications
functional descriptions
use cases
standards
etc.
Determine which documents and other information you will create:
product descriptions
installation guides
configuration guides
system administration guides
alarm-clearing procedures
routine maintenance procedures
command reference guides
online help
error messages
notifications
tooltips
etc.
If the documentation is to include tooltips, error messages, notifications, and dialog boxes, develop a plan to ensure that the wording of these is consistent, clear, and grammatical. Since the design team rather than the documentation team often writes the error messages and tooltips, etc., contact the system architect to work out the details of your plan.
I once worked at a multi-national company where each developer wrote the tooltips and error messages for the small part of the application he or she was working on, with the result that the tooltip for each Name field was innumerable variations of "Enter the customer's name, 5 to 20 characters," and that many error messages were ungrammatical, cryptic, different when they should have been identical, or just plain amusing. Here are some of those error messages:
At least one subscriber is associated to this group
Bad formatted ID
Managed object probably exists already
Cannot access Naming service. Is running ok?
Cannot contact Naming service. Is running ok?
Attempt to build a client request with a not supported yet request info type
Determine how the documentation will be delivered to the customer:
on paper
on CD
integrated with the software
If the documentation is to be integrated with the software, contact the system architect to discuss how the user will access it:
through a Help button on each GUI panel
through a menu item
through the F1 key
If the documentation is to be delivered on CD, plan how you will burn the CDs and label them. Determine whether users will need to dump the contents of the CD onto their hard drive before they can access the documentation. How will you convey this information?
If the documentation is to be delivered on paper, determine who will print and compile it. If a printing company, look for printers in your area and establish the lead-time required. If you, ensure that you have:
the required amount of paper
binders
tab separators
card stock for the covers and spines
For online help, determine what users will see after they click the Help button. Will they go to a topic that describes how to use a particular screen in the application? Will they go to a table of contents? Will they go to a Getting Started page? When creating online help, it is essential to plan how users will navigate through the help topics before you start writing.
Determine which desktop publishing software and help-authoring tool you will use. Order as required.
Work out the file structure and file-naming conventions for the documentation and online help.
For online help, work out the relationships among the different files. Will some help files be used for more than one GUI screen?
Create your templates.
The Writing Phase
Write your documents and make a list of glossary terms as you write.
During slow periods, research glossary terms using more than one source.
During slow periods, research the correct wording for copyright notices of any third-party and proprietary products that you mention in your documentation.
When the documentation is complete, do a spell-check and review your work from cover to cover.
Send the documentation to the subject-matter expert (SME) for a technical accuracy check.
Make the required corrections.
Send the corrections back to the SME for verification.
The Delivery Phase
For documentation that is integrated with the application, talk to the system architect to work out the final details of integrating the documentation.
For documentation that is to be delivered on CD, burn and label CDs.
For printed documentation, print each document and insert in binders. Insert tab separators as required. Insert spines and covers.
The Archiving Phase
Name your documentation folder on the network with the product name and version number. If you will be updating the documentation in future versions, create a new folder with the new version name and copy all the documents there.
If your company has a document archiving system, use it.
You are done!

BECOME A GREAT TECHNICAL WRITEREVEN IF YOU ARE NOT A GREAT WRITER

BecomeAGreat Technical Writereven if you are not a great writer Are you contemplating or beginning a career in technical writing? Have you been asked to create the user guide for your company's software application? Have you been asked to hire and manage a writer?
Where do you begin? How can you get an interview when you have no experience? How do you know if the technical writer on your team is doing a good job or a poor one? Can you find out before you hire the person?
Technical writers (known as technical authors in the United Kingdom) translate and organize complex information into user guides that any person can understand and use with ease. But in the 16 years that I have been in the business, I have often found myself working with writers who do not really know how to write manuals or use the desktop publishing software, and with clients who are not entirely sure what to expect from writers. More often, I have had to clean up a documentation mess left behind by a previous writer. This asymmetry between expectation and output can create technical writers who unknowingly make the same costly mistakes year after year, and clients who regard technical writers as a high-cost, low-value drain on the company's bottom line.
This site, whether you are a manager or a technical writer, will get you all working on the same page. If you are a writer, you will see that technical writing requires skills other than the ability to write. In fact, it is possible to write great user guides even if you are not a great writer. You don't need to spell perfectly (I don't), and you don't need to know the difference between a dangling participle and a dangling gerund. But although you don't have to be a great writer, you will probably be happier in the job if you like writing and are a competent writer. If you find it difficult to organize your thoughts and put them down in writing, you might find the job boring, unpleasant, and unrewarding.
In fact, writing is only a fraction of what you will do as a technical writer. This site, therefore, does not show you how to become a great writer—many other sites exist to help you with your grammar and style—but it does provide you with information, skills, tips, and techniques that can help you become a great technical writer.
Notes For Managers If you are a manager, this site shows you what you can expect from the technical writers on your team. Although this site speaks mainly to the writer, you will easily be able to develop from the information provided your own expectations and requirements for your writers. This site will also help you distinguish between good and bad technical writing and it will tell you what to look for when hiring a writer. In particular, you should read the first three articles below.

HOW TO BECOME A WRITER

Dear friend, everyone amongst us has a flair for writing a book. Each one of us, in our entire life time, does a little bit of story writing. But when someone chooses writing as career, then he finds this big question in front of him, how can I become a writer?
But you know something? You can become a writer by writing! Yes, it is pretty simple. If you do some little bit of research, you will find that there are no real secrets. You write on your own. You put words in a row and then it becomes a sentence. It then turns out to be a paragraph and then a whole page. If you sit tight over a few hours and try your hand at writing, you will come out with a positive result. Then you have to have sincere efforts over doing it again and again, because practice makes perfection. Unless you spoil a couple of pages, you won’t get the perfection in your writing style. Your style gets improved with practice and more practice.
But there is a problem. It is not very simple for everyone. Not at all that simple. Someone may have problem getting started. And if they do, then they may not keep the pace of writing. They lose the patience and enthusiasm. You can overcome this problem by maintaining your pace with strong determination. You need to be very determined to keep that pace because you start judging you inability to write due to failure attempts and this leads to understating your self-esteem. It becomes more difficult to start it over again. A man who wins is a man who thinks he can. So just do not let your attention wander as writing is a serious business.
Another way of keeping your determination intact, pace of writing, self-esteem is to declare yourself as a writer. And that will make all the difference. You write because you want to communicate something to the people or you just want to write. So you make sure that you speak out or tell people that you are a writer. Feel the sensation that these words create. Experience it. People would ask you about your writings etc. This will make you confident.
When you get along with your writing, just have a look on the place of writing, as it is and it should be a sacred place. Have your table and chair put in a separate room or part of a room. Get some flowers to put in a vase, lamp, dictionary, papers, stylebook, etc. That would make you comfortable and confident. If you have a computer and a printer, it is well and good as it would help you in writing. Make use of the Spell-check utility. Get yourself subscribed to any good-quality “Writing Journal”.
Try to learn from others. Make some friends who are good at writing. Listen to others. If you like some quotes or writing style, then note it down in your diary. It would help you in building/improving your writing style. Read good writings, as reading the best and good writings will play the part of a best teacher.
Finally, it is writing that would make you a writer. So keep writing. Writing is to write and write and write and write and write and write and write. Just don’t think of writing, simply write it down. Dreaming about the writing is not writing, writing the writing is writing. So make sure that you write everyday for a few hours. Make it a habit and at the appointed time. Sit tight for a few hours and you will come out with a writing as I have come up with this one for you. One fine day, you will be a writer who writes.

ON BECOMING A WRITER

"TAK ADA RESEP YANG LEBIH BAIK UNTUK MENJADI PENULIS KECUALI


DENGAN MENULIS SEKARANG JUGA!!"


"PENULIS YANG BERBAKAT GAGAL MENEMUKAN BANYAK ALASAN UNTUK TIDAK MEMULAI TULISANNYA."

"SEMENTARA ORANG-ORANG YANG BERBAKAT SUKSES SELALU MENEMUKAN ENERGI SETIAP KALI GAGAL.!"

"SERINGKALI YANG MEMBUAT UJUNG PENA TERHENTI MENUANGKAN KATA ADALAH KEINGINAN UNTUK MELAHIRKAN TULISAN YANG BANYAK DISANJUNG ORANG, SEMENTARA YANG MEMECAH KEBUNTUAN ADALAHSIKAP APA ADANYA DALAM MENUTURKAN KEBENARAN."


RESEP MENULIS YANG PALING BAIK ADALAH: "TUANGKAN SAJA."