TECHNICAL WRITING 101 PDF
Technical Writing pdf - Ebook download as PDF File .pdf), Text File .txt) or read book online. Help you with the writing process. Help you improve your own writing. Point you to references for the future. This talk will: 6. “The fundamental purpose of scientific discourse is not the mere presentation of information and thought but rather its actual communication. It does not matter.
|Language:||English, Spanish, Indonesian|
|Genre:||Health & Fitness|
|ePub File Size:||15.84 MB|
|PDF File Size:||14.88 MB|
|Distribution:||Free* [*Regsitration Required]|
Production editing for printed documents and PDF files Hyphenation and bad . Technical Writing will show you that there's more to technical writing. Technical Writing A Real-World Guide to Planning and Writing Technical Content (Third Edition). Front Cover · Alan S. Pringle, Sarah S. O'Keefe. Technical Notes, general Series. Technical Writing made easier rev. , March by. Bernhard Spuida, [email protected]
Focus on Tasks One way to make sure your writing is easy to follow and action-based is to focus on tasks. If you want a bit more information about how to do a task analysis, check out this article: How to Do a Task Analysis Like a Pro.
In addition to completing a thorough task analysis, you should strive to include an action verb in every sentence. First, refrain from writing in the first or second person.
For example, instead of writing: Next you want to click in the Comments field and paste your comments. Write something like this: Click in the Comments field Paste the comment Notice how much more direct the second example is? Write something like this: Forward the email to the Marketing Director. Be Clear and Concise An important part of making sure your written materials are easy to follow is to be as clear and concise as possible.
Here are some time-tested design suggestions culled from my 20 years of experience as a professional writer and information designer: 1 Keep it simple.
Try to limit your color choices to your approved corporate or client colors. Anonymity comes with the territory. Your reward in technical writing is helping others accomplish complicated tasks and perform technical procedures, plus, a usually above-average monetary compensation. The natural sweep direction for the eye is from upper-left down towards bottom-right.
Try to align your text and images along that diagonal for easy reading. There are good and free open-source alternatives that is worth a look at. You may want to give the following open-source programs a try. OpenOffice, the king and queen of office suits. Available for PC, Mac and Linux platforms. Try NeoOffice if you own a Mac. The benefits of interviews with users By talking to users of a product. 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. This corporate information may conflict with how users would like to use the product. 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.
You may end up talking to the person who supervises the employees using a product instead of the employees themselves. For new products. Although technical communicators often act as user advocates by providing the information that the users want and need. Even if you manage to get access to customers for the interviews. When content underestimates or overestimates its audience. You need to provide background information.
Chapter 6: While writing your material. This chapter explains the many points you should keep in mind while writing technical content.
This analysis is an important part of writing good content. 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?
Technical writing examples
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. Style and terminology Before you start writing. The law does not require that private companies comply with the Section guidelines unless those companies are providing services and tools for the government.
Congress passed legislation that requires federal agencies to make their electronic content and information technology accessible. Screen reading software will read that alternate text to describe a graphic to a visually impaired person.
Visit www. These standards. In If you learn the guidelines before you start writing. Many companies institute Section standards as best practices. Style and terminology Answering these questions will help you understand your audience and write content that better meets their requirements. Accessibility standards When creating content. Different types of content You can divide up the content you need to create into several different categories. Interface information Interface information explains the function of a particular part on a product.
You can further point out specific parts with callouts. For hardware. 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. Figure 5: Many applications include ToolTips. Consider whether the effort in assembling this information is worthwhile.
Figure 6: As shown in Figure 6. A dictionary is a great example of reference information. For more information about DITA. Writing reference information is not particularly difficult although actually acquiring the information can be. A standard dictionary provides an enormous amount of information about words. It requires that you work closely with the software developers and use some complex tools. In technical writing. Many help authoring tools have contextsensitive help capabilities built in.
The advantages you get from online formats. Different types of content Building context-sensitive help can be technically challenging. When writing reference information. Reference information tells you what a function is. Consider making reference information available online to make searching faster and more powerful. But conceptual information explains under what circumstances feature A is a better choice than feature B.
Giving them long narrative text is probably not going to be popular. In a book. When you write conceptual information. There may be no need for a programmer-level reference. Topic-based writing and its benefits Some companies write content as topics: Not every product will have task-oriented and reference information. Topic-based writing and its benefits Procedural information Procedural information consists of steps that tell a user how to perform a task.
Some products often have just a task-oriented user guide that tells the user how to install and use the product. Because most content has a great deal of information about how to use a product.
Topic-based content provides the following benefits: The next chapter. Features of three printer models X You and other authors write topics about the features. Making the change in a single location also ensures consistency. Table 2 shows a feature map for the printers. Automatic updating eliminates the need for figuring out where topics are used in your source files and for making the same changes in the different locations.
To gain an understanding of how topic-based authoring works. You can find more information about creating topicbased documentation in Single Sourcing: Figure 46 on page shows the process for a DITA-based workflow. Differences in style and presentation become glaringly obvious when dissimilar topics are placed one after the other in a deliverable.
If you are working in a topic-based workflow. Last-minute fixes. A smart doc plan writer knows this and creates a schedule to accommodate changes. If there are changes beyond the freeze point. Slipping schedules on a project fall into the same category as death and taxes—you can count on them. Last-minutes changes sometimes mean that there are some trade-offs.
Make these sorts of decisions with the involvement of the client and the documentation team. Experience is the best teacher Writing content for the first time is intimidating. Audience should always be a top concern. There are many issues you need to remember while writing audience.
Experience is the best teacher automatic updates. If it all sounds like too much to handle. Even though time or lack thereof will play an important part in deciding on any compromises. As you work on more and more projects. If you do guess. Technical writing seminars. Take what little information you do have and make your best guess. A vivid imagination can be most useful Every once in a while. One possibility in such desperate circumstances is to extrapolate.
To begin documenting the software. Figure 7 shows a sample procedure. Chapter 7: Writing task-oriented information When you create an outline for content. This chapter is not an exhaustive resource on how to write task-oriented material. This chapter explains what you need to think about while writing procedures. You need to keep your audience in mind at all times. Elements of a procedure Whether it explains how to use a piece of software or how to bake a cake.
Grate the carrots in the food processor. Note Note: Five large carrots make approximately 3 cups of grated carrots. Elements of a procedure Figure 7: Sample procedure Steps that each represent an action or a logical group of actions Introductory or lead-in information Cross-reference Before beginning to mix ingredients for your cake.
Place the carrots in one of the bowls and set aside. Figure with a figure caption Figure 2 Grate carrots with food processor left or grater right 4. Wash the carrots. The following sections provide details about how to handle the elements of a procedure. Preheat the oven to degrees.
Some companies take a more minimal approach by eliminating lead-in sentences or information about the results of completing a step. Breaking down a task into steps You or another member of your team have already written an outline that breaks down the tasks you need to document.
If necessary. A lead-in can also briefly explain how completing a task fits into bigger scheme of using the product. If you do use sentences for lead-ins. Writing task-oriented information Introducing the procedure Before readers dive into a list of steps.
When you start writing the content.
Difference Between Copy Writing and Technical Writing
A lead-in sentence or paragraph can do just that. Select the Edit menu. You can also group the actions of typing a command and pressing Enter: Type ftp at the command prompt.
By following a pattern in writing your procedures. Including the results continue the process of breaking down information— you break down the tasks in the outline into the steps within procedures. In content that explains software. Step 1 in the sample procedure tells the user to just turn on the oven. As Figure 7 on page shows. Including the results When writing procedures. Following the example shown in Figure 8.
Writing task-oriented information Figure 8: Show the result of an action in a step 1 Select the Format menu.
The Master Page Usage dialog box is displayed Figure Figure 21 Master Page Usage dialog box When including the result of an action. The Master Page Usage dialog box is displayed. Select the Format menu. Use notes for information that needs to be mentioned but that is a bit off-topic. A danger notation indicates the possibility of serious injury or death. A note contains information that is helpful to the user but that does not involve damage to the product or physical danger. If the information concerns possible damage to the product or danger to the user.
In a software manual. Adding notes. See Figure 7 on page for an example of a note. A warning may explain certain actions that will damage components. In a template-based workflow. Writing task-oriented information dealing with medical software. Be judicious about inserting notes into the text. Using bulleted and numbered lists In general. Overusing notes diminishes their importance and can be an annoyance for readers. Using bulleted and numbered lists dangers to ensure user safety and to reduce product liability.
For lists of items or choices which do not have a particular order. Figure 9: In content for software. Many documentation groups do not like lists that contain just one item. To make your cake and the icing. In structured authoring environments. Letting illustrations tell the story Sometimes.
The bulleted list communicates the same information in a much clearer way. Writing task-oriented information sentence. Letting illustrations tell the story Figure Figure 14 New Format dialog box In content about hardware. If you do insert a graphic. In online content. The New Format dialog box is displayed Figure Include a figure caption to explain its purpose. Figure 11 shows a table with headers on the columns and a caption. You can also add a table caption. See Chapter 8. Writing task-oriented information When deciding whether to include a graphic.
If your product uses a nonstandard Open dialog box. Organizing information in tables Tables are yet another way to communicate information particularly information that is repetitive or has a pattern.
Table 2 Icing ingredients Ingredient Amount Cream cheese. Some elements may be optional for example. The best way to ensure that the user references the correct item is to use a cross-reference. Tables can be helpful in reference material for example. Inserting cross-references Figure Tables are useful for information that has a pattern Table 2 lists the ingredients for the icing. Writing task-oriented information Cross-references in printed documents In printed documentation.
Figure Simple cross-reference Use the following kitchen appliances and hardware while baking your cake and making the icing: In printed documents. If you manually typed the page numbers for your cross-references. If your text development software has a crossreferencing feature. Links in online content In online content and PDF files.
In the second large mixing bowl.
Dayforce HR Guide
Cross-reference with page number 1. Table 1 on page 4 lists the ingredient amounts. Writing task-oriented information pointing. To make links in online content distinct from standard text.
If you are creating online content by converting source files for printed books. Cross-reference link in help file Link is underlined. Page numbers are not needed in online links.
You can also point to other content: Inserting cross-references If you directly author online content. Before linking to any content. Many companies have strict rules about linking to online material and that sometimes includes information created by the company itself.
Perhaps the name technical writer is a bit misleading. As you create your documents. Traditional graphics include several different types of illustrations.
Introduction to Technical Writing | Technical Writing Tutorial
Photographs are great for showing real-life images or highly detailed information. CAD drawings can also be used to create animations that zoom in on a particular part.
Animated screen shot showing how to complete a task in FrameMaker: Chapter 8: Visual communication In online content.
CAD graphics show exact. As always. The same is true of video clips in online content—they show the exact process a user should follow to complete a task. You can include rich media that incorporates both visuals and sound: Line art lets you simplify a piece of machinery and show just the parts that you want the reader to focus on. Using graphics in content Line art. When you store images on a computer. The vector image file contains a series of mathematical equations that describe the image in the file.
Understanding graphic file types In the physical world. Vector images In mathematics. This chapter focuses on the technical details of adding visuals to your content. A simple image. Vector images are graphics that are made up of vectors. Using graphics in content what they need to know before you decide which type of image or rich media to use. For information about designing visual information. From there. How vector graphic information is stored 2. Draw a line two inches to the right.
Visio is especially good for flow charts. Start here. Visual communication instructions something like this: Some tools. Other tools for this kind of work include Adobe Illustrator. Bitmap images Bitmap graphics handle photographs with ease.
Photographs consist of thousand or millions of dots. Unlike the vector image of the box in Figure Vector images. Using graphics in content Figure 16 shows a typical example of vector art—a Venn diagram.
Each square in the grid has a unique address and a color. Vectors are not an efficient way to describe a photograph. A bitmap graphic stores information in a grid. This is what the file might look like if it were written in English.
Certain file formats are always bitmaps. How bitmap images work Black. File formats Graphic files come in many different file formats.
But for photographs and screen shots. Figure 17 shows how bitmap editors describe a picture. Table 3 provides some recommendations for graphic formats. This is the image. This is an inefficient way to draw a box—the vector version is much simpler. Using graphics in content Table 3: Keep in mind. You want to be sure that readers can identify the main point of the illustration immediately. To preserve every data point. Scope of an illustration One important consideration in creating graphics is to give your readers context.
JPEG provides good compression for photographic images. In Figure Providing too much information makes it difficult for readers to locate the item you want them to see The image is so large. In this image. Now readers can locate the item you want them to see For every graphic you include in your document.
Too little information leaves the reader lost Figure 20 shows a better approach. Using graphics in content the image lacks context. Refer to the online help for your operating system for information about changing display settings. Both the Macintosh and Windows operating systems have built-in screen capture functions. Even if a project requires screen shots taken on multiple operating systems. Visual communication Displaying information from your computer screen Most software documentation uses pictures of the interface.
Authors should also check their screen resolution settings. Your style guide should specify the display and resolution information for taking screen shots. All of these tools let you take a picture of an entire screen. There are many programs for taking screen shots. The resolution affects the size of dialog boxes. Consult the help for your operating system for more information.
When colors scheme When multiple authors are working on a project. When you update the graphic. When you embed a graphic. Each of these techniques has advantages and disadvantages. Table 4: Linking vs. When you embed the graphic. Using graphics in content Placing graphics in your content After you create your illustrations or screen shots. Updating When you update a graphic.
Before doing so. When you link a graphic.
Portability To move a document file from one location to another. If all graphics are embedded. Figure 21 shows an easy way to organize your content and graphic files. The same is true if you are authoring HTML content for the web. Visual communication For technical documentation projects. In the example. Check the user manual or online help for more information. Use one DPI setting consistently—this is especially important if multiple authors are creating content.
Some applications have commands for scaling graphics. If you need to modify the size of a graphic after placing it in a file. Using graphics in content Keeping graphics uniform in size When you place a graphic in a document file. Visual communication Figure While recording. You can also write down a list of the actions you want to show in the video tutorial. Programs such as Captivate and Camtasia streamline the process of recording the action on your screen.
While planning. If you make a mistake while recording. Using rich media content Using rich media content More and more technical information is delivered online.
To prepare. Moving too quickly may make it hard for users to follow the action. Creating animated screen shots and other rich media Creating an animated screen shot may seem daunting in comparison to capturing a still screen image.
Continue with the rest of the demo. Visual communication pause recording to gather your thoughts. Flash is an expensive and complex tool. You can use the Flash application to create multimedia content that combines still images.
Although basic players for the many proprietary formats are generally free. Understanding rich media file formats File formats for rich media are more complicated than those for static images—most formats are proprietary to the companies that make them. Tom Johnson provides several excellent tips for creating video tutorials on his blog. Much of the advice for creating still images applies to motion files: Using rich media content At the time of this writing.
Rich media content is rapidly evolving.Planning a schedule for a book means scheduling your writing time. Many companies have additional components in their release cycle.
Contents Appendix B: Touch typing is nice. If youre a freelance writer or if your company is creating content for another company, the identity of the client is obvious. Have you read a poorly written manual for a household appliances or an electronic device?