tech writing sunset, know this: most of the manuals and guides out there are written by .. Dummies publishers have a book on everything from writing résumés to .. tablets onto the factory floor, replacing PDF work instructions with mobile. Technical Writing Guide. Michigan State University. Department of Biosystems and Agricultural Engineering. Farrall Hall, East Lansing, Michigan. The five-way access system of the Handbook of Technical Writing . Using PDF Files . Previously, he worked in advertising, technical writing, and.
|Language:||English, Spanish, French|
|ePub File Size:||23.51 MB|
|PDF File Size:||17.65 MB|
|Distribution:||Free* [*Regsitration Required]|
This books (Technical Writing For Dummies [PDF]) Made by Sheryl Lindsell- Roberts About Books Title: Technical Writing for Dummies. Editorial Reviews. From the Back Cover. "Technical Writing For Dummies is a must-have reference for both the aspiring and seasoned technical writer." — Carol. PDF Drive is your search engine for PDF files. TEACHING TECHNICAL ENGLISH WRITING AUTOR: From Warriner's English Grammar and Composition .
Although technical communicators often act as user advocates by providing the information that the users want and need. Final preparation—production editing Now. Editing your index Be sure to include your new subentries as their own main entries as well. Sarah S. Including the results continue the process of breaking down information— you break down the tasks in the outline into the steps within procedures.
Preface In the second major section. The third section explains some advanced topics. A solid review by an editor or a fellow writer can make you look good by catching your mistakes before the client or users see them.
Chapters in this section are: Learning about the translation process before you start writing the English content can save your company a lot of time and money—and prevent many. A thorough. A good index can also save a company money—readers who quickly find the information they need are less likely to call customer support.
These technologies have changed the way users get information about products. Preface affects technical writers. This book focuses on developing content for computer hardware and software. The appendices provide information about getting a job.
The appendices are: Preface such as writing about manufacturing environments. You start with a complicated piece of technology. But perhaps a better definition is someone who can explain complicated concepts in clear. This deceptively simple mission requires more than just writing ability and an understanding of technology—although both of those skills are critical.
A technical writer is really a translator. As a technical writer. You also need people skills and investigative talent.
In many cases. This chapter describes the four basic skill sets every technical writer needs: Chapter 1: They must absorb new information and then understand. Many experienced technical writers create several new books each year. The stereotypical crabby. You can learn about new developments in technology by subscribing to computer magazines or online mailing lists.
In most jobs. You should be willing or even eager to learn about new technology as it develops. You should also understand basic concepts such as databases. For example. If your job requires that you write about something particularly technical. See Appendix B for more information about resources for technical writers.
By putting typing speed on your resume. If using a keyboard is a laborious. This experience should play a critical part in how you write your content: Touch typing is nice.
Your initial lack of knowledge. If spending most of the day at a keyboard typing seems unappealing. Your typing technique is not important. Decent typing speed is a basic necessity for any technical writer. As you learn how to use the new hardware or software. Writing ability Who treats the doctor and who documents for the writer? After all. Writing ability Writing skills are an essential component of technical communication.
Enormous technical knowledge is not a substitute for writing ability. You may not think of yourself as a computer expert. Often always? It seems terribly obvious to say that a technical writer should be able to write. They do not want to spend a lot of time explaining the product to you. Some programmers are excellent writers. Writing should be: Chapter 6. Your readers probably have well-tuned B.
Even though the first example would probably make your high-school English teacher happier. In some cases.
Select the name of the building you work in. But you should spell-check. While writing. Which of the following steps would be better suited for that information? Select the name of the building in which you work. Style guidelines specify how you should capitalize section headings.
Writing recipes. Ask a friend to try your recipe and see whether you forgot any steps. By far the best way to improve your writing skills. But to succeed as a technical writer.
You obviously need the ability to organize information in your document. Arguing about nitty-gritty style issues is a great way to waste time and make yourself look unproductive. If your writing skills need work. Many fiction writers belong to writing groups. Organizational skills Almost every job requires some organizational skills. Planning a schedule for a book means scheduling your writing time. Organizational skills you work. Consider taking a seminar on project management and be sure to maintain a calendar or spreadsheet with scheduling information.
In many companies. To ensure that you can meet project deadlines. All of this probably sounds a bit intimidating. Project management software can also be helpful. If you are the only writer in a company. Many writers are confident about their writing and technical ability but are intimidated by the project management and scheduling requirements of the job. You might have to ferret through piles of technical specifications to find exactly what you need. And unlike writing a novel.
Strong detective and people skills To create content. Learning how to communicate and get what you need from busy technical experts is a skill you cultivate over time. Now that you have an idea of the skills you need as a technical writer. Chapter 5. Where do you get the information you need?
Sources include technical specifications. This book can be a helpful resource for them. Strong detective and people skills Part-time contributors need technical writing skills.
What you can expect maybe Creating technical content. Make the changes noted. Make the changes identified by the SMEs. Tasks include outlining. Deliverables can include books. Chapter 2: The technical writing process end of the project. A template is a file that contains all of the paragraph styles. During a real-life project.
What you can expect maybe 10 Produce the material that is. Do you assume that they will restore the features before the release. Some groups go beyond templates by defining a structure that content must follow. Or do you hedge your bets by making a copy of the information but removing it from the content for now? Every project is full of happy surprises like these. To complete the steps in the content development process.
At this point. The rest of this book provides more information about how the technical writing process works and offers helpful information about how to handle the inevitable bumps in the road. Authoring with templates and with structure In general. Chaos is exactly what you think it is: There are no repeatable processes in place to guide authors while they develop content. Each author develops content in a different manner.
Authoring with templates and with structure The first two levels. Because templates provide predetermined styles. Figure 1 on page 42 shows the application of paragraph styles to text. In the chaos and page-consistency scenarios. Page consistency means that content looks the same on paper or other delivery format. Template-based authoring At a minimum.
Even though users see consistent formatting. As a result. Chapter 9. The technical writing process Figure 1: Structured authoring More and more technical writing departments are implementing structured authoring.
In template-based publishing. Authoring with templates and with structure styles should be applied. Writers work in software that validates their content. Figure 2: Hierarchy of a section Section Title Herding your cats Para Here are some reasons why you should never herd your cats: In addition to enforcing structure.
In structured authoring. Instead of typing content and applying styles. Authors no longer apply paragraph styles or need to know which styles are allowed in particular contexts. Figure 2 shows a hierarchical view of the cat-herding example in Figure 1. Chapter The formatting can look just like what is shown in the template-based example in Figure 1 on page Are templates and structure really that important?
Later chapters in this book explain how working in a template. In a later step. Despite this increased demand. The demand for having content in multiple formats— print. In some structured workflows.
The technical writing process Based on the location of each element within the hierarchy shown in Figure 2 on page Authoring with templates and with structure processes in place. Templates and structure also provide the foundation for single sourcing. The specifics of single-sourcing processes vary depending on the tools authors use to develop content and create final output.
In short. Both printers have the same paper feeder. Only one of the printers has a memory card reader. Single sourcing requires that authors create content in a consistent manner—and following a template or structure ensures that consistency. You can create different versions of content and multiple output types. For more information about single sourcing and how documentation groups implemented it. Single sourcing is now considered standard practice for the technical writing industry.
Now that single sourcing is standard practice. When we released the first two editions of Technical Writing Formulating doc plans and outlines is the best way to complete this analysis. You probably want to start writing the content instead of spending time on plans and outlines. All you need is some information about the product. The time you spend planning your content is an investment. But as a staff writer in a software company.
A doc plan should contain information about the following: Although early prototypes and specs never give you all the information you need and frequently are inaccurate because the product has changed. Very necessary evils—doc plans and outlines In other words. To create a documentation plan and outline for each deliverable. It may be your documentation manager. For a sample documentation plan. A documentation plan describes all the components of a content development project.
Most often. This list should also include any rich media content such as videos you plan to deliver. FoogleGarber rejects all cookies and other identifying characteristics requested by a web server. For more information on rich media. This might only be a sentence or two: The more you know about your audience. You should provide as much information as you can about each type of user.
This should include their education level. Chapter 4. A schedule should also include dates for editing. The product developers will provide technical assistance and ensure the accuracy of content.
Client will review content for accuracy and completeness. Doc plans for external clients If you are producing a documentation plan for an external client. Cost may be a fixed price or an hourly rate. Who writes the doc plan? In a group of writers or a documentation department. Client is ultimately responsible for the content of the content. Performing this analysis early in the project helps prevent nasty surprises later. As you create the plan.
Any formulas for writing doc plans? A doc plan contains lots of numbers page counts. Some reasonable estimates are as follows: Very necessary evils—doc plans and outlines If your plan requires commitments from other people. Even experienced writers cannot pinpoint exact page counts or days of work with certainty. At the end of every project. If you think that some factor.
As you complete more projects. In your particular environment. Your plan can give you the ammunition you need to convince your manager that you need some temporary help. To calculate page count. If you have a deliverable on a very aggressive schedule. Creating these estimates is a bit of a black art.
Your best bet is to play with the prototype. You will not be able to keep the outline for all of that in your head. What goes into the outline? To write the outline. In high school or college. In reality. Creating an outline will help you break down the manual into manageable chunks. Outlining requires you to think about what needs to be covered. If you create an outline. Based on your research and the information you find in the existing documents.
See Chapter 5. This might include product design documents. User content for related products is also useful for gathering ideas about what your document should contain.
This is where your ignorance or ability to fake ignorance of a product is really useful. Use the mindset of a new user while you figure out what needs to be documented.
Very necessary evils—doc plans and outlines graphics from one file type to another. As a new user. Providing two sets of content separates out the day-to-day tasks from the high-level tasks that only users with special rights on the system can perform.
How many deliverables should there be? Here are some things to consider while determining how many different deliverables there might be: Once you have a list of tasks.
Writing the outline Some word processing programs Microsoft Word. Your manager or a more experienced writer can help identify any items you may have forgotten.
Do whatever makes sense to you. Your outlines can be part of your documentation plan or stand-alone documents. Instead of using a rigid outlining structure with Roman numerals. The chart will include cross-references to detailed procedures. For more information on rich media content.
Defining employees—procedure explains how to define employees that work at each job site. Very necessary evils—doc plans and outlines Figure 3: Entering job data This chapter will contain the following sections. Section will also explain how to change and delete process types. For deliverables that include audio and video. Plant A in North Carolina. Section will also explain how to group employees according to job functions and how to change and delete employee information.
Section will also explain how to change and delete job sites. Defining process types—procedure explains how to define the departments and areas through which a job flows.
Defining job sites—procedure explains how to define the job sites with which work may be associated for example. You could post a draft of an outline. For more information on wikis and other collaborative technologies.
The wiki shows you when changes were made and who made them. There are many free wiki technologies available including TikiWiki at info. Wikis also offer calendars and other functions that can be useful for planning and tracking content development efforts.
With an internal wiki. There are many word processing. Chapter 4: Some of the programs listed in this chapter are open source programs you can download for free. You may not use a document processing tool if your department creates only online content. See page for information on open source technology. Although Word is adequate for short business documents.
More information on the PDF format: Many technical writers use a basic word processing program such as Microsoft Word. For writing documents that will be printed. FrameMaker is specifically for creating and maintaining long technical documents. These packages are less oriented toward book production but are better than FrameMaker at producing full-color. See Chapter If you are working in a structured authoring environment.
If your content needs to look like a very expensive annual report. They are also common with other applications technical writers use: If you plan to create different kinds of output from your document for example. XML is a specification for storing structured content as text. Paint Shop Pro. Arbortext Editor. Some software packages such as Paint Shop Pro can handle both screen shots and graphics processing.
For UNIX. Graphics software and clip art packages information. Snapz Pro is available. For the Mac. Graphics software and clip art packages To create the screen shots.
Most operating systems have built-in but basic tools for screen shots. Tools such as Captivate and Camtasia record what happens on screen. For drawing line art for example. In addition to buying packages of clip art. Keep in mind that you want a high-quality selection of clip art and that some clip art packages have restrictions on the number of times you can use an image and where for example.
For graphics processing or editing. A clip art package can be helpful when you need icons in your text such as a stop sign to flag warnings. The player for showing Flash files is free.
Flash enables the creation of animations and interactive content. Rich media tools Now that more and more content is being delivered online. For online help. RoboHelp and Flare also have conversion capabilities. Help or web authoring tools online ad that includes action and sound. HTML Help. File conversion and single-sourcing utilities There are many third-party tools that convert wordprocessing files to other formats.
Getting formal training is the best option. The ability to create multiple types of output from one set of files is called single sourcing. The Acrobat Reader. Some companies convert their word processing files with third-party tools to PDF format and online help.
Most documentation departments have instituted some form of single sourcing. Low-cost or free online tutorials.
If training is not a possibility for you. This software is hard to use! Some of the tools listed in this chapter—particularly for text development. Web browsers have some FTP capabilities. These tools. FTP software lets you transfer the files over the Internet without using email. A good rule of thumb is not to send an email attachment larger than two megabytes MB.
On the PC. You can also use online file transfer services such as www. Some of these applications are open source tools you can download for free.
For information about open source tools. Compression is essential when sending large files via email. Even if you are the only person on a project.
Microsoft Project is a widely used projecttracking tool. In your company. Your company may also have specific configurations for the tools. That way. Keep in mind that both the sender and the recipient will need the software. You can create such a calendar for free at web sites such as Yahoo www. You can also use a web-based calendar that all team members access. Computers and ergonomics good idea to check the system requirements of applications to ensure your computer meets the specifications.
Because technical writers do spend so much time in front of the computer. This will help minimize scrolling through your pages. Some things to consider about your work environment and how you work in it include the following: At an absolute minimum. Also consider using two smaller monitors instead of one large monitor.
For this reason. This chapter explains several sources from which you can extract information. Ferreting out that information can be the most difficult aspect of technical writing.
When the spec answers your questions. As work progresses on the project. Typical information in a spec includes: Chapter 5: Getting information NOTE: In general. If you ever see one. The software developer will tell you. Getting information Organizing menu information: Prototypes and software under development The term prototype is used a little differently in hardware and software. In fact. As a writer.
A hardware prototype often does not have all the working parts. This may or may not match how the interface is organized. All major features are sort of working. If at all possible. Expect alpha software to crash your system at regular intervals and possibly corrupt it. Slightly better than prototype software is prerelease software. Table 1: Software release cycle Development stage Status Alpha Software works.
Otherwise known as the windows that the user sees on screen. It may crash occasionally. Beta Software works. This version is often made available to customers for testing. Expect beta software to work with minor glitches.
Some major features are missing or not working. Alpha 2. Of course. Getting information Table 1: Release Candidate status requires a freeze on interface changes and no code changes except to correct bugs.
Many companies now distribute software online and include automatic updating capability in their applications. RC software should be stable with no crashes. Products may go through several alpha versions Alpha 1. In other words. General Availability GA Software is done and shipped to customers. Alpha 3 before moving on to beta status.
All features are working and major bugs have been cleaned up. RC status means that no more features will be added. Many companies have additional components in their release cycle.
The distinction between beta and GA software is becoming fuzzier. The drawbacks of prototypes and prerelease software Like a spec or any other source of information. Prototypes and software under development procedures and to take screen shots for your document. Be sure that when the development team makes changes. The same applies to hardware prototypes. If you are taking screen shots of a software interface or are creating hardware diagrams.
Hardware diagrams often come from computer-aided design CAD programs. At some companies. The intellectual property and copyright agreements should be separate from the NDA. Many companies ask employees to sign a nondisclosure agreement NDA. Small software companies are especially notorious for changing things up to the very last minute. This is a true story.
In addition. Most NDAs are straightforward. The writers were required to cover the prototype with a large box whenever they left the room so that no one could look in and see the printer.
One good approach is to ask the developers which parts of the product are more stable so that you can write about those first. The NDA spells out your obligations to keep information confidential and to safeguard proprietary information. If you are working on a product whose features or existence have not yet been announced. You can also develop a process that accommodates those changes with iterative releases and content that is auto-updated along with the software.
If the content is well written. Legacy content completed. Reviewing content for similar products can also be helpful. This can save you from having to rewrite a topic several times as the product changes. Developers and subject matter experts The people who are developing a product—or the SMEs very familiar with a product—are the most important source of information a writer has.
The best way to avoid this situation. Good communication between product developers and technical writers is essential to the success of a content project. Review the material before you accept the job and make sure that you and your potential employer agree on what needs to be done. If the product has changed significantly since the last release. Not only do developers create the prototypes. Getting information useful takes as long as writing quality content from scratch.
The drawbacks of developers and SMEs Sometimes developers are so busy working on the product. To avoid problems with grammatical nitpicking. If an editor or another writer will review the work for grammar and adherence to the style guide. Their review comments ensure that your content is technically accurate.
In some extreme cases. Reviews then run late. Developers and subject matter experts The benefits of developers and SMEs Developers who promptly answer your questions and review content on schedule are your best allies on a content development project. If the developers warn you that particular features are going to change. Getting a solid review from the developers is essential because only the developers know whether content is technically accurate.
Deliver content that requires only minimal changes from the developers. What are some of the ways you can ensure that developers give you the information you need? See the following sidebar. Getting information reviewers that they do not need to focus on those issues.
If the developers respect your work. If the developer prefers to talk at the water cooler. If the developer prefers to be contacted by email. Bring bagels and cream cheese to a morning review session. Without a thorough review by the development team or SMEs. Consider using medieval torture devices. Try to group your questions instead of interrupting her constantly. When working late. Learn to read code and dig up information by scanning the code.
Deliver one or two chapters for review at a time instead of the entire document. Split up reviews so that developers review only the material they are responsible for.
Restrict the questions you ask the developer to the really obscure stuff. Cold hard cash. If all else fails. Explain exactly what happens and how to reproduce it.
Save up questions and make a list to give to the developer instead of asking individual questions. When inserting queries for the developer in your document. And lots of them. Develop enormous expertise in your product. The product engineers are more likely to take your questions seriously if they think you know your stuff.
This is not likely to help. Developers and subject matter experts Almost 30 ways to get information from developers 4.
When reporting bugs to the developers. Getting information Almost 30 ways to get information from developers Copy your manager on correspondence to developers. Report bugs to the developer personally instead of the bug-tracking system—many developers are evaluated based on the numbers of bugs reported against their code. Schedule a standing weekly meeting to review questions. Send your manager a note explaining the drop-dead date when you need review comments.
Most users turn to search engines such as Google instead of going directly to company web sites. Users can tell you what they stumbled on so you can be sure your document clearly explains the issue.
The benefits of interviews with users By talking to users of a product. You may end up talking to the person who supervises the employees using a product instead of the employees themselves. This corporate information may conflict with how users would like to use the product. Even if you manage to get access to customers for the interviews. For new products.
Getting information The drawbacks of interviews with users Tight budgets and aggressive schedules on content development projects often make user interviews impossible—interviews are expensive and time consuming.
Although technical communicators often act as user advocates by providing the information that the users want and need. You need to provide background information. Chapter 6: This analysis is an important part of writing good content. This chapter explains the many points you should keep in mind while writing technical content.
When content underestimates or overestimates its audience. While writing your material. Such content is a failure. Have you read a poorly written manual for a household appliances or an electronic device? Manuals and online help should help people use products—not make them feel stupid. Writing to the correct audience will prevent a great deal of user frustration.
The K. Your readers will see right through this. You should also be careful about making assumptions about your audience based on demographics or educational level. The rule of thumb for technical writing is that you should write at an eighth-grade level. For example, consider these choices: The WinkleWart finances.
The WinkleWart her finances. The first two options are not inclusive. Consider the fourth and fifth options. Common sense should prevail. But in the real world, you rarely have the time or money to send out detailed user questionnaires, interview prospective users, or use other sophisticated techniques.
There are, however, a number of questions you can ask to get a sense of your audience: For example, where do they live, how old are they, and is English their primary language? You might also consider translating the content. Professional computer users, such as programmers or system administrators, have different content requirements than computer novices. They are, however, unlikely to be computer experts. If your product is a database of legal information for the general public, you cannot assume that the reader will have legal knowledge or computer knowledge.
Does the user want to use the product? If you are writing about a digital camera, you can probably assume that most of your readers are interested in using the camera and want to learn about it so that they can take good pictures. The clerks who have been using the paper filing system for years know exactly how to use the old system. But now, they must learn a new, computer-based system, which may not be popular.
A more highly motivated reader is more willing to invest some time reading content to learn about the product. What do the users need to do with the product? Do they need to know how to do everything or just a how to use a few important features? These limitations will affect how you design and deliver the content. For example, older readers or readers with limited vision will not appreciate small, cramped fonts. If your audience includes people who are blind, you need to make sure that your content is comprehensible to someone who hears it or that it works in Braille.
Congress passed legislation that requires federal agencies to make their electronic content and information technology accessible.
Style and terminology Answering these questions will help you understand your audience and write content that better meets their requirements. These standards. The law does not require that private companies comply with the Section guidelines unless those companies are providing services and tools for the government. Screen reading software will read that alternate text to describe a graphic to a visually impaired person. Accessibility standards When creating content.
Visit www. Style and terminology Before you start writing. If you learn the guidelines before you start writing. In Many companies institute Section standards as best practices.
For hardware. Interface information Interface information explains the function of a particular part on a product. Different types of content You can divide up the content you need to create into several different categories.
You can further point out specific parts with callouts. Figure 5: Different types of content Figure 4: You can provide an overall view and then zoom in on the most important part of the picture in a separate image Hula man For software. Many applications include ToolTips. As shown in Figure 6. Figure 6: Consider whether the effort in assembling this information is worthwhile. For more information about DITA.
Writing reference information is not particularly difficult although actually acquiring the information can be. Different types of content Building context-sensitive help can be technically challenging. In technical writing. Many help authoring tools have contextsensitive help capabilities built in. The advantages you get from online formats. It requires that you work closely with the software developers and use some complex tools.
Embed Size px. Start on. Show related SlideShares at end. WordPress Shortcode. Published in: Full Name Comment goes here. Are you sure you want to Yes No.
Be the first to like this. No Downloads. Views Total views. Actions Shares. Embeds 0 No embeds. No notes for slide. Book details Author: Sheryl Lindsell-Roberts Pages: For Dummies Language: English ISBN Description this book Title: SherylLindsell- Roberts Publisher: If you want to download this book, click link in the last page 5. You just clipped your first slide!