This action might not be possible to undo. Are you sure you want to continue?
archiving The phases of the technical writing process 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 1. Gather existing information—any or all of: requirement specifications functional descriptions use cases standards contracts etc. product descriptions installation guides configuration guides system administration guides alarm-clearing procedures routine maintenance procedures command reference guides online help error messages notifications tooltips
2. Determine which documents and other information you will create:
error messages. If the documentation is to be delivered on paper.. If the documentation is to be integrated with the software. it is essential to plan how users will navigate through the help topics before you start writing. determine who will print and compile it. . ensure that you have: the required amount of paper binders tab separators card stock for the covers and spines 8. If a printing company. 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 6. If you. How will you convey this information? 7. and grammatical. Determine whether users will need to dump the contents of the CD onto their hard drive before they can access the documentation. Determine how the documentation will be delivered to the customer: 5. develop a plan to ensure that the wording of these is consistent. contact the system architect to work out the details of your plan." and that many error messages were ungrammatical. Since the design team rather than the documentation team often writes the error messages and tooltips. For online help. etc. Is running ok? Attempt to build a client request with a not supported yet request info type on paper on CD integrated with the software 4. 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. cryptic.3. If the documentation is to be delivered on CD. and dialog boxes. with the result that the tooltip for each Name field was innumerable variations of "Enter the customer's name. plan how you will burn the CDs and label them. clear. 5 to 20 characters. 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. 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. determine what users will see after they click the Help button. different when they should have been identical. notifications. look for printers in your area and establish the lead-time required. If the documentation is to include tooltips. or just plain amusing.
burn and label CDs. The Delivery Phase 1. research glossary terms using more than one source. During slow periods. Work out the file structure and file-naming conventions for the documentation and online help. Will some help files be used for more than one GUI screen? 12. talk to the system architect to work out the final details of integrating the documentation.9. with an eye to highlighting points particularly relevant to software documentation. For documentation that is integrated with the application. 6th edition (Alred et al). 5. 3. Preparation Research Organization Writing a draft Revision In the next few sections I will go through these steps in more detail. work out the relationships among the different files. Send the corrections back to the SME for verification. 7. Make the required corrections. research the correct wording for copyright notices of any thirdparty and proprietary products that you mention in your documentation. Insert spines and covers. Order as required. When the documentation is complete. For printed documentation. Insert tab separators as required. print each document and insert in binders. 2. Send the documentation to the subject-matter expert (SME) for a technical accuracy check. do a spell-check and review your work from cover to cover. Determine which desktop publishing software and help-authoring tool you will use. During slow periods. Preparation . For documentation that is to be delivered on CD. (See Writing Glossaries for more information. 10. 6. Write your documents and make a list of glossary terms as you write. 4. 5.) 3. 2. 2. 4. The Writing Phase 1. lists five steps to successful technical writing: 1. Create your templates. For online help. Principles of Technical Writing The Handbook of Technical Writing. 11.
and how that information can best be conveyed. but to give an overview of the documentation process. Before I sat down to write this tutorial. use a chronological method of development. your readers. I asked myself some questions. The purpose is not to turn each and every Perl Monk into a technical writer. such as the ability to link to more information. This is important: writing for the web is not the same as writing for print or any other media. you will want to go with a sequential method of development: step 1. so a conversational writing tone is appropriate.but can you explain it? Organization Poorly organized documentation may in fact be worse than no documentation. It's a diverse community with wide skill levels from complete novice to Perl gurus. step 2. this tutorial is an online article presented on a web site. This community is focused on Perl. Research The purpose of documentation is to convey information. Consider what you need to tell users. if you're writing installation instructions for a program. I'm covering fairly basic material. For example. Who is the audience and what do I know about them? The audience is members of the Perl Monks community. In general-to-specific . Choose the method that best suits your subject. You can think of this step as being broken down into four tasks: Establishing the purpose of the document Assessing the audience Determining the scope Selecting the appropriate medium Let's look at this document. If you're writing a history of versions. but since this is a tutorial. and your purpose. you must understand it. In order to convey information. and so on. In software. The web also has features that print does not. In this case we are talking about your code. of course! More generally. often used methods of development are division and classification (explain each parts function and how the parts work together) and general-to-specific. What is the medium? Perl Monks. What is the purpose of the tutorial? To provide an introduction to technical writing/documentation. Use these features to the fullest. What works well on paper may not work on the web. What is the scope? This is an introductory tutorial.Writing requires preparation. It's a fairly friendly and informal place. so hopefully you understand it .
and move to more specific information. punctuation. Some advise not worrying about matters such as grammar. there's a checklist for all five steps of the writing process. and revision takes up a page of its own. and covers a topic clearly.development. you begin with general information about the function of the software. spelling. I use an iterative approach: I start with a very broad outline. but don't use it as a substitute for . In my technical writing text. Once you've decided on an organization scheme. When revising. you can begin writing. I usually write fairly polished drafts. such as Technical Writing/Documentation Tutorial Introduction Principles of Technical Writing Preparation Research Organization Draft Revision Conclusion References I then go through my outline and break categories into sub-categories and sub-sub-categories until I feel I have a clear enough map. prepare an outline. Expand your outline into paragraphs. Check your spelling and grammar. since you will have a better idea of what is covered in the body of the document. How you outline is a personal choice. Personally. You may wish to save the introduction for last. I broke the Preparation category up in this manner: Preparation Purpose Audience Scope Medium Writing a Draft Once you have your outline. Personally. You will also need to write a conclusion to your document . check for completeness and accuracy. This provides a road map for your writing. Check that your writing is concise. (Introduction) Tell them. For example. Use spell check. The first four fit on the first page.remember the basic rule of technical writing: Tell them what you're going to tell them. I find it difficult to follow this advice. and layout at this point. (Conclusion) Revision Revision is one of the longest steps of this process. you will be revising your work in the next step. (Body) Tell them what you've told them. Regardless of your tactic.
having someone proofread your work is a good idea. You may regard it as an opportunity to learn. the subject of the sentence performs the action. acronyms. How many times have you been frustrated by a bug and posted it on Perl Monks. I'm sure many of you have had the experience of spending hours looking for a bug in your code. simple sentences o Eliminate unnecessary words (filler words) to reduce sentence lengths 4. 1. and the next day come back to see the problem staring out at you. writing. not a passive voice o In an active voice. Use bulleted/numbered lists o Use bulleted lists to create separation between similar ideas o Use numbered lists for steps and sequences o Limits the number of items in a list (six to eight) o Properly introduce each list with a complete or incomplete sentence 6. You give up. Likewise. and revision. determining the scope. and general-to-specific. In this tutorial.proof-reading. Define acronyms o Spell out each acronym on first use . only to get a quick response from someone else pointing out the problem? The same thing works for revision. organization. as if in boldface. frustrated. methods of development used in software documentation were introduced: sequential. Conclusion You may regard documentation as a chore. “was”. In organization. Avoid wordiness o Avoid using redundant words and phrases o Use concise words instead of wordy phrases 5. Keep sentences short o 15 – 20 words per sentence o Break long. such as. Outlining was also discussed. I've presented the steps used in technical writing/documentation: preparation. in a passive voice. In preparation. Review the mechanics: are abbreviations. “is”. strategies for writing and revision were covered. Regardless. Finally. complex sentences into shorter. o Subject – verb – object o Passive verbs are longwinded. Write in an active voice o Write in an active voice. the subject is the recipient of the action. division and classification. “were”. and initialisms expanded at their first usage? Don't do your revision in one step. make sentences sound “wordy” o Passive sentences usually include a form of the verb “to be”. The research section covered the reasons for research and strategies for commenting code. assessing the audience. chronological. “are” and “been” o Use Spelling & Grammar feature of Word to track your use of passive voice 2. key points discussed were: establishing the purpose. research. and selecting the appropriate medium. Use familiar words o Use familiar words instead of complex words o Complex words are also referred to as technical jargon 3. you do need to document your code. “am”.
This action might not be possible to undo. Are you sure you want to continue?
We've moved you to where you read on your other device.
Get the full title to continue listening from where you left off, or restart the preview.