Technical Writing for Techies

67 %
33 %
Information about Technical Writing for Techies
Product-Training-Manuals

Published on June 1, 2007

Author: Abhishek

Source: authorstream.com

Technical Writing for Techies:  Technical Writing for Techies CATS Conference March 2005 Ginger Stockdale stockdal@mail.sdsu.edu Objectives:  Objectives Upon completing this workshop you will be able to: Define the differences between academic and technical writing. Identify the characteristics of effective technical writing. Identify the steps in the writing process. Identify the components of good design. Identify the steps in organizing and writing instructions. Identify some tips to help your documents. Define the differences between Web versus Print. Identify some tips to help your web pages. Academic vs. Technical Writing:  Academic vs. Technical Writing Purpose: Knowledge of Topic: Audience: Criteria for Evaluation: Academic Demonstrate what you know about a topic Less than teacher who is evaluating them Teacher Depth, logic, clarity, unity and grammar Technical Getting something done More than the reader Several People Clear and simple organization of ideas Consider These Statements….:  Consider These Statements…. Looking into the azure blue sky one could see the golden orb of the sun slip gently beneath the western sky. The sun set in the west. What is Technical Writing?:  What is Technical Writing? “Technical writing is the art, craft, practice, or problem of translating that which is logical into that which is grammatical. Technical writing forms a bridge between the logical (the primarily binary concepts understood by computers, robots, lawyers) and the illogical (the haphazard, inconsistent concepts misunderstood carbon-based life forms, highly intelligent computers, lawyers) via the medium of the grammatical, the haphazardly logical system incomprehensible to both. The practice of technical writing presupposes that you, the illogical, actually want to learn about the logical subject, which of course is in all cases false. This basis in a false presupposition makes technical writing a pursuit typically favored by those with arts degrees from obscure universities.” -Hitch Hikers Guide to the Galaxy What is Technical Writing (really)?:  What is Technical Writing (really)? “Technical writing conveys specific information about a technical subject to a specific audience for a specific purpose…The words and graphics of technical writing are meant to be practical: that is, to communicate a body of factual information that will help an audience understand a subject or carry out a task.” -Michael H. Markel Director of Technical Communication Boise State University Characteristics of Effective Technical Writing:  Characteristics of Effective Technical Writing The four C’s: Clarity -- it is easily understood by your intended audience Comprehensiveness -- all of the necessary information is present Conciseness -- it is clear without excess verbiage Correctness -- it is grammatical and follows conventions Steps in the Writing Process:  Steps in the Writing Process The ADDIE instructional design model can be used: Analysis Design Development Implementation Evaluation Theory of Design:  Theory of Design Good design is: Visually simple and uncluttered. Highlights structure, hierarchy, and order. Helps readers find information they need. Establishes the organization’s image. How to Organize Instructions:  How to Organize Instructions Title--explains what a reader will do. Introduction--explains what the instructions should accomplish, who should follow them, lists any needed tools, knowledge, cautions, or definitions. Body--describes steps in a sequential order, it may include graphics to clarify instructions. Conclusion--describes expected results. How to Write Instructions:  How to Write Instructions Number each step and start with a verb. Don’t use: Alt and F1 pressed simultaneously. Do use: 1. Press the Alt and F1 keys simultaneously. Put steps in sequential order. Don’t use: Insert the disk into drive A: after turning on the computer. Do use: 1. Turn on the computer. 2. Insert the disk into drive A:. How to Write Instructions (cont.):  How to Write Instructions (cont.) Begin instructions with an imperative. Don’t use: From the edit menu, choose delete. Do use: Choose Delete from the Edit menu. Describe each step separately. Don’t use: Click Start, point to Programs, and click Uninstall. Do use: 1. Click Start. 2. Point to Programs. 3. Click to Uninstall. How to Write Instructions (cont.):  How to Write Instructions (cont.) Indent any explanations under the appropriate step. Don’t use: After you press F3, the screen will show the first menu. Do use: Press F3. The screen will show the first menu. Highlight warnings or cautions so readers don’t overlook them. Don’t use: If you push the delete key all of your data may be lost. Do use: Caution! If you push the delete key all of your data may be lost. How to Write Instructions (cont.):  How to Write Instructions (cont.) If a step is to be carried out only under certain conditions, describe the conditions first. Don’t use: Enter the order number in Field 6 if the order will be filled by our warehouse. Do use: If the order will be filled by our warehouse: 1. Enter the order number in Field 6. Single-space the information within a step, double space between steps How to Write Instructions (cont.):  How to Write Instructions (cont.) Group multiple steps under subheadings. Don’t use: 1. Click on the Objects menu. 2. Click on Select. 3. Click on Add to select one object. 4. Click on the object you want to move to select it. 5. Click on the Edit menu in an icon editor window. 6. Select move. 7. Click right on an origin point. 8. Move the cursor to the new location. 9. Click right to place the object at the new location. Do use: Selecting an Object 1. Click on the Objects menu. 2. Click on Select. 3. Click on Add to select one object. 4. Click on the object you want to select. Moving an Object 1. Select an Object. 2. Click on the Edit menu in an icon editor window. 3. Select move. 4. Click right on an origin point. 5. Move the cursor to the new location. 6. Click right to place the object at the new location. How to Write Instructions (cont.):  How to Write Instructions (cont.) Use parallel structure. Don’t use: 1. Use the left mouse button to click on the Tools in the command menu at the top of the design window. 2. Select Analysis from the Tools menu. 3. Choose Imitation from the Analysis menu. Do use: 1. Click Tools at the top of the design window. 2. Click Analysis on the Tools menu. 3. Click Imitation on the Analysis menu. How to Write Instructions (cont.):  How to Write Instructions (cont.) Use between 5-9 steps per subheading. Create a clear, inviting format by using numbers, letters, indentation, bold-face and lots of white space. Keep instructions short and clear. Don’t leave out the articles (a, an, the). Tips to Help Your DocumentsWriting:  Tips to Help Your Documents Writing Use an “If-Then Approach.” Example: If you choose "Yes," the program will make Outlook your default email client. If you choose "No," it will set Hotmail as your default email client. Use Active Voice. Don’t use: It is recommended that the document be saved frequently. Do use: We recommend that you save your document frequently. Use Present tense. Don’t use: You will need to name the file Test. Do use: Name the file Test. Tips to Help Your DocumentsWriting:  Tips to Help Your Documents Writing Write positive language. Don’t use: Access to student information is not authorized for any parties except Enrollment Services. Employees who have access to student information are not allowed to share that information with non- affiliated third parties if you have not authorized it. Do use: Access to student information is authorized only for Enrollment Services purposes. Employees who have access to student information are required to protect and keep it confidential. DON’T WRITE IN UPPER CASE FOR MORE THAN A WORD OR TWO. Tips to Help Your DocumentsWriting (cont.):  Tips to Help Your Documents Writing (cont.) Use lists whenever possible. Use the title to define the task. Use headings and subheadings. Label segments in away that reflects how readers are likely to think about the operation or procedure. Don’t use: Components Do use: How to Check the Components Tips to Help Your DocumentsWriting (cont.):  Tips to Help Your Documents Writing (cont.) Provide only one way to do something within a step. Be precise with your instructions. Use warnings. Write a conclusion. Example: Congratulations! You’ve just created your first document! Don’t annoy the reader. Tips to Help Your DocumentsDesign:  Create visual fields by using white space. Use 1 to 1.5 inch. margins for the document. Distinguish information by using spacing and formatting tools. Use graphics when appropriate. Tips to Help Your Documents Design Tips to Help Your DocumentsDesign:  Use Serif (Times New Roman) fonts for body/regular text. Use Sans Serif (Arial) fonts for titles, headings, and short phrases. Use no more than 3 font types per document. Use 10- or 12- type size for body text and 14- (or larger) for headings or titles. Tips to Help Your Documents Design Web vs. Print:  Web vs. Print Users read print but scan web content Users read print sequential but navigate web content Scannable Content:  Scannable Content Users seldom read online. They scan the page for keywords and phrases. Web content must be edited to be scannable. For scannable content, it must be bulleted less than half the print content highlighted with keywords Navigable Content:  Navigable Content Credibility is important for web content. Readers often want to know the source of information behind the document. Authors must not be afraid to let readers visit other sites. Content must be navigable with outbound hypertext links similar articles or web sites Tips to Help Your Web PagesWriting:  Write at an 8th grade level. Chunk your information. Keep your paragraphs short. Less is better. Control the text width by using columns. Tips to Help Your Web Pages Writing Tips to Help Your Web PagesDesign:  Serif fonts don’t work well on screens unless they are large. Use Sans Serif fonts for most information. Font sizes should be scaleable. Use contrasting colors for text and the background of the page. Avoid busy backgrounds. Tips to Help Your Web Pages Design Summary:  Summary During this workshop we: Defined the differences between academic and technical writing. Identified the characteristics of effective technical writing. Identified the steps in the writing process. Identified the components of good design. Identified the steps in organizing and writing instructions. Identified some tips to help your documents. Defined the differences between Web versus Print. Identified some tips to help your web pages. Sources for Additional Information:  Sources for Additional Information Designing and Writing Online Documentation William Horton Wiley; 2 edition (1994) ISBN: 0471306355 How to Communicate Technical Information Jonathan Price and Henry Korman Addison-Wesley Professional (1993) ISBN: 0805368299 Managing Your Documentation Projects JoAnn T. Hackos Wiley; 1 edition (1994) ISBN: 0471590991 Microsoft Manual of Style for Technical Publications Microsoft Corporation Microsoft Press; 3rd edition (2003) ISBN: 0735617465 Writing Software Documentation Thomas T. Barker Longman Publishing Group; 1st edition (1997) ISBN: 0205195768 Thank you for your time!:  Thank you for your time! Please don’t forget to fill out the evaluation forms! Ginger Stockdale

Add a comment

Related presentations