Examples of Technical Writing
The most common examples of technical writing are: User manuals; software installation guides; Standard Operating Procedures (SOP); Service Level Agreements (SLA); Request for Proposal (RFP); legal disclaimers; company documents; annual reports; and Help files.
User manuals are documentation that accompanies various consumer electronics such as televisions, cellular phones, or gaming consoles. The technical writer must write a manual that a novice (the target audience) will easily understand. User manuals usually contain: Photographs; disclaimers; numbered diagrams; sequenced directions; flow charts; a trouble shooting guide; the warranty; and contact information for the Help Desk or Customer Support. Ideally, the engineers and programmers familiarize the writer with the product during a site visit in the planning phase. More often, the writer self-teaches operation of the device. Through the self-teaching process, the writer anticipates problems that a typical user would face. The writer learns how to address those problems and contacts the experts for explanations, if necessary. The writer incorporates only the most common problems and solutions in the troubleshooting guide. Unusual or improbable situations are best left to the Help Desk or Customer Support staff. The user manual must be very easy to follow, because technical support by phone is extremely expensive, and the customer may return the product if it is too difficult to understand.
Software Installation Guides
Computer software must be equipped with documentation to guide the user through the installation process. Often, the programmers automate the process and the writer just authors alert boxes and the Read Me file.
Standard Operating Procedures (SOP)
Most organizations have well-defined processes for accomplishing routine tasks. An SOP can document how to process payroll, hire a new employee, or calculate vacation time. SOPs ensure that multiple people in the organization can perform the same tasks in an identical manner, so quality is consistent. SOPs help eliminate favoritism and irregularities. SOPs ensure that co-workers can assume the responsibilities of an absent, vacationing, or terminated employee with no variation in performance and minimal time lag.
Service Level Agreements (SLA)
An SLA is a binding contract between a provider and a customer. It outlines services, guarantees, warranties, and other negotiated items between the two parties.
Request for Proposal (RFP)
An RFP is similar to an SLA, in that they both describe future work or services to be accomplished. An RFP differs from an SLA in that the former is used as a pitch to a potential customer during a bidding period. Therefore, the RFP is not a binding, concrete agreement.
Legal Disclaimers
A legal disclaimer is also called a hedge clause. It is a statement by the publisher that defines the terms of service. The publisher attempts to limit its liability in the event of a lawsuit. The publisher wants to be protected and held harmless if an injury results from the use of the document. Basically, the publisher seeks to disavow a future claim by the reader/viewer. The publisher states there is no implied warranty or contract with the reader/viewer. Here is an example of a legal disclaimer for a Web site that offers software templates for download, courtesy of freenetlaw.com:
We will not be liable to you (whether under the law of contract, the law of torts or otherwise) in relation to this website or the templates for any direct, indirect, special or consequential loss; or for any business losses, loss of revenue, income, profits or anticipated savings, loss of contracts or business relationships, loss of reputation or goodwill, or loss or corruption of information or data.
Most legal documents are extremely detailed. Although the U.S. government requires plain language in its documents, other legal documents may contain terms confusing to the layperson. The publisher may ask the writer to simplify and rephrase the "legalese" of the disclaimer elsewhere in the document.
Company Documents
Most companies have some type of orientation manual for new employees to read and understand. Orientation manuals usually contain these elements:
- Company's history
- List of services, products, and divisions
- Organization chart outlining the hierarchy
- Map of the facility
- Employee rights and responsibilities
- Dress codes
- Hours of operation
- Rules and regulations
- Disciplinary process
- Policies regarding attendance, accident reporting, vacation, salary, confidentiality, proprietary information, performance reviews, and sexual harassment
- Job descriptions
- Disaster response plan and safety procedures
- Educational opportunities
- Common forms
- Orientation checklist
- Glossary
Annual Reports
Companies must provide annual reports to inform their shareholders about the prior year's stock performance and other financial information. Some non-profit organizations also prepare annual reports. The technical writer spends a great deal of time compiling information and then presenting it in an attractive and comprehensive manner to shareholders.
Help Files
Help files are necessary for any type of software. The purpose of Help files is to make the user independent. Remember that Help Desk or Customer Support Staff are very expensive and reduce company profits. Write the Help file for a novice user with no prior knowledge of the system. Aim at the Grade 8 level and define technical terms in a glossary. (If this seems like "dumbing down", recall that John F. Kennedy's most memorable speeches were written for a Grade 8 audience.) Break all procedures into sequential steps. A procedure should have no more than 10 steps. Take screen shots. Link related information.
Business Plan
Every company needs a business plan to obtain financing and ensure its continued success. The business plan has ten sections:
- Executive Summary briefly describing on one page the:
- Business concept, product or service
- Target market
- Owner(s) and key personnel
- Legal entity (sole proprietorship, partnership, or corporation)
- Founding date
- Location
- Financials (funding, sales, profit, cash flow, equity, collateral or security, and return on investment)
- Product or service description, clearly stating its value to the customer and its current state of development
- Description of the management team, including licenses or special training, their goals, and if they worked together previously
- Market and competition analysis, including growth potential
- Marketing and sales analysis, including price, distribution, fixed costs, product placement, payment policies, and promotion
- Business system and organization (traditionally, a Managing Director overseeing R&D, Production, Marketing, Sales, Service, Finance, Human Resources, Quality Assurance, and make-or-buy partners)
- Implementation schedule, including start dates, hiring, depreciation planning, and investment milestones
- Opportunities and Risks, including profit and loss projections
- Financial Planning, including funding sources, planned income statement, projected balance sheet, liquidity, the break-even point, investor's return, and a five-year forecast based on reasonable assumptions
- Appendix, including an organization chart, patents, resumes for the key personnel, and articles or reviews written about the business
Release Notes
Release notes begin with the title of the software and its current version, followed by the date the new software is released to the consumer, for example, OmniWriter 2.0.4 Released August 26, 2009. Beta notes include the software's uses, the platforms on which it will operate, and its capabilities. Subsequent release notes outline the programmers' fixes, for example:
- Updated for Mac OS X 10.2
- Added "Check for Updates" menu item
- Fixed five-second timeout if unable to connect to the server