What Is Technical Writing And Documentation
- 1. Anjali Priyadarshini 19 and 20 Jan 2008
- 2. What is communication? Technical Writing Business Writing Proposal Writing Project Management White papers FSD/SRS Writing Web writing Articles Presentations AV movies/demos
- 3. How does writing at work differ from writing in college? Serves practical purposes Addresses complex audience Addresses international and multicultural audiences Uses distinctive types of communication Employs graphics and visual design to increase effectiveness Requires collaboration Is shaped by social and political factors Is shaped by organizational conventions and culture Meets deadlines Is produced with advanced computer technology Is sensitive to legal and ethical issues
- 4. The best way of honing your skills in communication is to read anything professionally written…whatever, whenever, wherever!
- 5. How well you communicate affects your career Survey 1 Survey 2 Survey 3
- 6. How well you communicate affects others Explosion of Space Shuttle Challenger Engineers knew beforehand of the faulty O-Ring design They were unable to convince the managers at NASA about it Bottomline: Sensitivity to legal and ethical issues
- 7. What is technical communication? Requires the collaboration of: Technical writer Technical editor Information architect Usability expert User interface designer Technical artist Technical trainer Process of conveying information about scientific, engineering, or technological topics, done by a technical communicator Purpose is to disseminate useful information effectively that enables the reader to solve whatever problem she is facing with a particular technology
- 8. Who is a technical writer? A person who creates meaningful and effective documentation for a technology that is accurate, readable, accessible and helpful to the intended audience Technical writing is a subset of technical communication done using specialized desktop publishing tools SMEs provide information on the technological concepts through various forms of knowledge transfers and validate the resultant content for accuracy
- 9. What are some of the problems readers face? Too technical Too verbose Poor grouping of topics and therefore, poor usability Content and technology mismatch Grammatical and presentation errors Localization of language – misses the larger global audience
- 10. What is the role of technical writing? Present facts through quality content, using easy-to-understand language and format If the document does not communicate useful information to the user as intended by the writer, then the communication is meaningless Audience Design Purpose
- 11. What are the styles of writing and which one does the writer adopt? Narrative How-to Lists Tables Graphics Audience Design Purpose The technical writer adopts a writing style that fits all the key requirements of successful communication as accurately as possible Assess the audience – all sets of audience that you expect to read the document Define the objective Select the format – arrangement of content on a page Craft the style – structure, language, illustration
- 12. What are the basic considerations for a technical writer? Who are the readers of the user documentation (and the users of the product)? Is the material complete? Is there background material that needs to be referenced here/kept in mind while writing? Does it meet the needs of the users of the products? Can the readers understand the document? Is it easy to find things in the document? Do you like the layout of the document?
- 13. What is the normal process flow for creating a technical document?
- 15. Conducting research – Knowledge transfer Exploiting your own memory and creativity Searching the Internet Using the library Interviewing Conducting a survey
- 16. Planning for usability and persuasion
- 17. Can you make your draft more usable? Can you make your draft more persuasive? Does the content project the employer's point of view? Will the draft impact others in the organization? Does your draft promise something your organization cannot deliver? Does your draft comply with your employer’s policies? Check it from your readers’ perspective. Read your draft more than once, focusing on different issues each time. Check for errors missed by the computer program you used. Send your draft for a peer review and an editorial review Sample checklist for checking draft documents
- 18. Translating your plans and objectives into content Announce your topic – present the big picture Present generalizations before details Move from the most important topics towards the least important Reveal the organization of your content – headings, transitions, forecasting statements Keep in mind cultural, regional and ethical considerations
- 20. Formatting Format is the arrangement of type on a page and the layout of the document Bottomline: Use the most suitable format – usually a combination of organization guidelines and personal experience What font would be most suitable? What type face? What type size? How do I depict association, emphasis and hierarchy?
- 21. Mechanics
- 22. Editing Start with the most important changes
- 23. Structure and Style Structure that enhances understanding End Start Orients readers to document Tells readers what happens in document Prepares readers for the middle Strong headings and logical organization puts the message across clearly to the reader Analyze results and make recommendations Supply secondary information Glossary for unfamiliar terms Middle Title Summary Introduction Middle Sections Conclusion Back Matter
- 24. Language “ Words differently arranged have a different meaning, and meanings differently arranged have different effects.” - Blaise Pascal
- 25. Language The 15ATS series toggle switches, in excess of 200 in total, were subject to the extreme of temperatures caused by being in close proximity to the furnace. This in turn caused heat failure as the expansion of metal caused a fault whereby the metal connection fused. The heat of the furnace has to be over 600 degrees Fahrenheit before this effect takes place. Over 200 automatic toggle switches fused when the keypad melted as the furnace temperature rose to over 600 degrees Fahrenheit. Too technical; may not match reader knowledge
- 26. Language From any page of a site, links can be found which point to other pages in the same site or to other sites, wherever they may be. Specifically, these links are addresses which are called URLs. However, what is interesting for the visitor is not the address itself, but what can be found there, and so generally the address is not displayed. Instead, what you find there is highlighted in the text (by underlining it and displaying it in another color, often blue). You can link any page to other pages on the same site or different sites. These URL addresses, usually hidden from view, guide the user to the right page. The user can then click on any underlined text, often shown in blue, and more information pops up. Unnecessary details
- 27. Language The QMS Magicolor 2 Printer is equipped with two interfaces, one is known as the parallel interface, the other is known as the Ethernet interface. Whatever interface connection is needed , you will find that MS Windows 98 has already been preinstalled and your software applications are based on this platform. (50 words) The QMS Magicolor 2 Printer has Parallel and Ethernet interfaces. Whatever interface you need, you will find your software applications will work on the preinstalled MS Windows 98. (28 words) Passive verbs
- 28. Language The experiment was conducted so that the relationship between the two theories could be examined . First, the cultures were prepared and then were examined under the microscope to see if any impurities could be found . Once the purity of the samples could be established, they were used in six independent tests. (51 words) The experiment examined the relationship between the two theories. First, microscopic examination for impurities isolated pure examples used in six independent tests. (22 words) Too complex
- 29. Language Physical inventory records can be accurately kept for exchange transactions by reduction of the inventory from the receiving report and requiring customer services to prepare a production report on repaired items going back into the inventory as a replacement for items that have been sent to the customer in exchange. (One Sentence—50 words ) To keep inventory records accurately for exchange transactions: Reduce the inventory from the receiving report. Ask customer services to prepare a production report on repaired items and list the replaced items sent to the customer on the inventory. (Three sentences—Total 40 words) Rambling sentence
- 30. Language As we noted in the preceding section, if you purchased additional printer options , such as a second printer tray, it is a requirement you verify its correct installation. As we noted in the previous section, if you bought extra printer equipment, such as a second printer tray, you must check that you installed it correctly. Too many complex words
- 31. Language Most refractory coatings to date exhibit a lack of reliability when subject to the impingement of entrained particulate matter in the propellant stream under extended firing durations. The exhaust gas eventually chews the coating of existing ceramics. Too much jargon
- 32. Language Problems arose in a number of areas of the stock transportation device that required intervention by an appropriately qualified member of staff so remedial action could be taken. As the temperature rose to 120 degrees Fahrenheit, the coolant for the metal rollers overheated causing the conveyor belt to jam. To keep the belt working, a mechanical engineer had to reset the timer and rollers on the conveyor belt, replace the coolant and slow the belt by 25% to 200 feet an hour. Monitoring the temperature saw a rise from 80.5 degrees Fahrenheit to 124.5 degrees Fahrenheit causing problems in the coolant’s temperature. As the coolant’s optimum operating temperature is 80 degrees Fahrenheit, the result was an expansion of the coolant beyond its maximum operating temperature level of 105 degrees Fahrenheit. This in turn led to a failure of the conveyor belt that was rectified by the mechanical engineer assessing the exact cooling coefficients needed with a possible ambient temperature above the manufacturer’s recommended levels. Three reduced settings were considered, namely reducing the belt speed by 10%, 20% and 25%. These would lead to a reduction in the in-line assembly velocity of 80 feet, 160 feet and 200 feet an hour respectively. The optimum setting was 25.32% of the previous 800 feet an hour rate. However, before this was set, the engineer had to replace the 3.5 gallons of coolant used and reset 42 or the 360 rollers on the belt. Too general Bottomline: Meaningful, factual, precise and simple sentences in the active voice with minimum generalizations
- 33. Superstructures Simple guides that help you prepare certain standard documents: Reports – Empirical, Feasibility, Progress Proposals Instructions Journals and White papers Each element of the structure answers specific questions that a reader may ask
- 37. Superstructures – Journals, Articles and White Papers
- 38. Superstructures To communicate precision of a complex image detailed or parallel information efficiently key details To give readers a visual rest stop “ Words differently arranged have a different meaning, and meanings differently arranged have different effects.” - Blaise Pascal
- 39. Illustrations The English nurse Florence Nightingale was an innovator in displaying statistical data through graphs. In 1858 she devised the type of chart depicted here, which she name Coxcomb. Like pie charts, the Coxcomb indicates frequency by relative area, but it differs in its use of fixed angles and variable radii
- 40. Illustrations
- 41. Illustrations
- 42. Illustrations Guidelines Make graphics easy to understand Use color to support message Integrate graphics with text – reference and caption Verify and validate illustrated data – include cross-references if any
- 43. Illustrations The testing hardware of the rocket shown in the figure has five main components: camera, digitizer, I/O interface, and mechanical interface. Commands are generated by the computer, then passed through the I/O interface to the mechanized interface where the keyboard of the ICU is operated. The display of the ICU is read with a television camera and then digitized. This information is then manipulated by the computer to direct the next command.
- 44. Technical Communication Tools Software programs that help us Create documents In word processing Integrate an array of media to create professional, engaging, interactive training content Access existing digital learning elements or learning objects for reuse in a new courses
- 45. Why do we need authoring tools? Authoring Tool Categories
- 46. Help Authoring Tools (HATs) A software program used to create online help Context sensitive help that the user can search and view without stopping/exiting application
- 47. Content Management System (CMS) CMS is used to manage content on websites Used interactively by contributors (Wikipedia based on wiki, a type of CMS) Used for archiving vast quantities of content and made available inter-office and over the web Content Management includes: Computer files Image media Audio files Electronic Documents Web content Main advantages Server based system that facilitates creation of repositories and enhances data accessibility, anywhere, anytime Workflow management and event messaging capabilities Easy organization, control, versioning and publication of content
- 48. Version Control System (VCS) Also known as Source Code Management (SCM) – used to electronically manage information that undergoes frequent revisions Word processing /HAT programs such as MS Word/Adobe Robohelp have standalone VCS embedded in the application Especially useful in multi-developer projects where the final outcome is a synergized version of the individual
- 49. Thank You