technical instructions essay

Link to facebook
Link to linkedin
Link to twitter
Link to youtube
Writing Tips

A Guide to Technical Writing (With Examples)

4-minute read

5th May 2023

You can find technical writing in lots of places, including in your home, at your job, in many industries, and in businesses of all sizes. If you need help with business writing specifically, check out how we can assist you .

In today’s post, we’ll break down what technical writing is and how to do it effectively. We’ll also provide some handy examples.

What Is Technical Writing?

Technical writing doesn’t always look very technical! It can be anything that describes how to do a task or how to operate a machine or system. Or it can cover a specialized topic. Technical writing includes recipes in your favorite cookbook, board game instructions, operator manuals, health and safety regulations, legal documents, and financial reports.

Instructions for Carrying Out a Task

This type of technical writing can be a recipe for a cake, the instructions for a board game, tips on how to walk your dog to heel, or the script for a social media video on how to cut your own hair.

Operating Manuals for Machinery, Appliances, or Systems

Technical writing can also be the user guide for a dishwasher, for a factory machine that makes cardboard boxes, a “how to” guide for spreadsheets, or instructions for changing the oil in your motorcycle.

Specialized Topics

The list here could be very, very long! Technical writing on specialized topics includes a company’s business reports, a medical consultant’s letter to a patient, health and safety regulations, employment policies, and legal documents.

So How Do I Produce a Great Piece of Technical Writing?

Let’s take it in three stages: Who? What? How?

Who Is It For?

In any type of writing, knowing your audience is important. This is particularly true of technical writing. Here are some examples of who might read technical writing:

· A renter of an apartment that needs details on their lease

· An electrical engineer who needs to know how the wiring is laid out in the apartment block

· The janitor of that same building who needs to know the location of the emergency lights

· The occupant of apartment 61, who needs to know how to use the oven in their kitchen

They all need information presented to them, but what information do they need?

What Do They Need?

The renter needs a legal document that leaves no room for doubt about their legal rights and obligations and those of their landlord. The document will be very detailed, containing terms that need careful explanation.

The electrical engineer needs accurate, clear information about the wiring, as they could get hurt or cause harm to someone else if the diagram is inaccurate.

The janitor needs clear directions and a map of where the emergency lights are.

The occupant of apartment 61 needs instructions that are written in plain English so they can use their oven safely.

How Should Technical Writing Be Composed?

Follow these steps when writing a technical document:

· Research and know your subject thoroughly.

Find this useful?

Subscribe to our newsletter and get writing tips from our editors straight to your inbox.

· Decide on the appropriate writing style. Just because it’s technical, doesn’t mean it has to contain lots of jargon . Be concise, be direct, and be straightforward.

· Consider whether you need to include diagrams, maps, images, charts, and/or tables.

· If writing instructions, take it one step at a time, write objectively , and make sure the instructions work!

Examples of Technical Writing

Let’s look at some examples:

The first version contains unnecessary words, but the warnings are not specific enough. The instructions should be concise and clear. In the second version, the danger is stated right away, and the critical warnings are concise and specific.

In these examples, the first version is unnecessarily wordy. It provides a lot of detail for minor tasks but gives vague instructions for bigger tasks. The second version is much clearer. The instructions are easier to follow, and they include each necessary step.

Good technical writing needs the following attributes:

1. Relevance

2. Accuracy

4. Accessibility

5. Simplicity

Really good technical writing will include these attributes every time.

Is technical writing difficult?

Technical writing does not have to be difficult if you follow our guide and do your research beforehand.

Are there professional bodies for technical writers?

There are several professional organizations for technical writing. This list from UTA Libraries is very useful.

What can I do if I’m not sure that my technical writing style is appropriate to my subject?

We have experts in many fields who can check your writing and advise on style .

Share this article:

Post A New Comment

Got content that needs a quick turnaround? Let us polish your work. Explore our editorial business services.

5-minute read

Free Email Newsletter Template (2024)

Promoting a brand means sharing valuable insights to connect more deeply with your audience, and...

6-minute read

How to Write a Nonprofit Grant Proposal

If you’re seeking funding to support your charitable endeavors as a nonprofit organization, you’ll need...

9-minute read

How to Use Infographics to Boost Your Presentation

Is your content getting noticed? Capturing and maintaining an audience’s attention is a challenge when...

8-minute read

Why Interactive PDFs Are Better for Engagement

Are you looking to enhance engagement and captivate your audience through your professional documents? Interactive...

7-minute read

Seven Key Strategies for Voice Search Optimization

Voice search optimization is rapidly shaping the digital landscape, requiring content professionals to adapt their...

Five Creative Ways to Showcase Your Digital Portfolio

Are you a creative freelancer looking to make a lasting impression on potential clients or...

Make sure your writing is the best it can be with our expert English proofreading and editing.

TemplateLab
Art & Media

Technical Writing Examples

33 good technical writing examples (word & pdf).

The advancement in technology inevitably leads to people training their skills in technical writing, a valuable asset. The skill is crucial, especially for those who work in tech-related businesses. Learning how to make technical writing examples gives you the ability to communicate knowledge. Technical writing skills don’t just involve understanding information and writing it down in a document but also taking high-level information and processing it into a more “digestible” content.

Table of Contents

1 Technical Writing Examples
2 What does technical writing mean?
3 Technical Writing Samples
4 Characteristics of technical writing
5 What is the purpose of technical writing?
6 Technical Writing Skills
7 Where is technical writing used?
8 Tips for technical writing

What does technical writing mean?

With regard to importance, technical writing is now at par with journalistic and creative writing. Many would feel surprised to discover that technical writing has existed since the dawn of writing language itself. People have used technical writing examples to transform complex explanations and equations then simplify them for average readers and laypersons to understand.

Take, for instance, a textbook. You may consider this a document done using technical writing because it takes complex ideas and breaks them down into more comprehensible bits for students. The main purpose of technical writing samples has nothing to do about entertainment or engagement. It was primarily created to teach the required information for learning how to perform a certain task.

Each time you purchase a product, it usually comes with a set of instructions, an instruction manual , rulebook, definitions or other such manuals. The writing used here is different types of technical writing. To learn how to master this skill, you should learn the right technical writing tips.

Technical Writing Samples

Characteristics of technical writing

If you have an interest in acquiring technical writing skills, you should know the important characteristics of the art. There various types of technical writing, each having its own purpose. What makes technical writing special is that it’s primarily informative, specifically in explaining different topics to other people.

It is commonly used in manuals and other technical documents that provide information and direction. L ike any other styles of writing, technical writing has its own characteristics including:

It’s very direct It doesn’t use terms that people don’t understand and shuns away from eloquent writing styles.
It’s straightforward and clear If you want to create a professional technical writing sample, stick to the subject matter and convey the information you’re writing about in a concise and clear manner.
It has a solid structure This means the style of writing has an easy-to-follow composition that makes it easy for readers to understand. Solid structure is the main feature of technical writing as it enables the readers to access the information they need easily.
It’s very informative and detailed The contents of materials written using technical writing skills should provide information by describing the topic as completely as possible.

What is the purpose of technical writing?

Every style of writing has its own objective. For a technical writing example, the purpose is to provide complex or confusing information to help people understand better a certain item like a computer, a new technological device, a new drug, and so on. It should also explain how a certain item works or how to finish a project .

The main target of technical writings is the people searching for information about a specific subject. The main goal is to make certain that the information provided is very concise, clear, and easy to comprehend. Technical writing can sometimes be very challenging for some people because it requires the reader to translate the information that’s hard to understand into terms that anyone can comprehend without any problems.

There are other informative types of writing as well, but it is only the technical writing style that focuses on clearly presenting the information in a specific way so that readers can utilize the information for different purposes.

Technical Writing Skills

Where is technical writing used?

The main purpose of a technical writing example is to share technical information with those who need to learn about a certain subject. It comes as no surprise why most of the occupational and technological fields like robotics, electronics, engineering, chemistry , and more all use technical writing when creating instructions for the operation of machinery, technologies or for conducting experiments.

The field of technical writing can be extremely complex, especially for beginners but you can avail of technical writing samples to create for yourself a textbook, manual or other technical writing documents. With these samples, you can help create a good tone and flow for your document and outline all of the information you intend to include in your material. Here are some of the most common technical writing examples:

Annual Reports As a rule, companies should provide annual reports for the purpose of informing shareholders about last year’s stock performance along with other pertinent financial information. Even non-profit organizations have to come up with annual reports. For this, the technical writer needs a great amount of time to compile information, then present these in a comprehensive and attractive manner to the shareholders.
Help Files In the digital world, these files are necessary for all software produces. The main purpose of these files is to make users independent. Businesses know that maintaining a Help Desk or a Customer Support Staff can be very expensive, thus, reducing company profits . You can even write a Help file for novice users who have had no prior knowledge of the software.
Legal Disclaimers The legal disclaimer is a statement that establishes the terms of service . You would write this to limit your liability in the event of any legal processes like lawsuits. You should make sure that you’re kept protected if anything bad happens because of the use of your document. In simpler terms, you seek to disavow any future claims made by readers.
Standard Operating Procedures (SOP) If you’re working in a company, you should familiarize yourself with its SOP. Most companies have these well-defined procedures for accomplishing routine tasks . For instance, an SOP can establish how the payroll process works, how new employees get hired or how to calculate vacation hours . The use of an SOP can ensure that several persons in the company can do the same task in the same way to ensure consistent quality of work. Moreover, SOPs eliminate irregularities and favoritism. It ensures that workers can assume the tasks of employees who don’t come to work, have gone on vacation or got terminated without any changes in performance.
User Manuals This refers to documents that usually accompany various electronics like televisions, gaming consoles, cellular phones, and the like. As a technical writer, you would have to write manuals that a novice will understand easily. The manual should be easy to follow otherwise the user will resort to technical support through email or by phone. If the manual is too difficult to comprehend, the customer might have no recourse but to return the product.

Tips for technical writing

Even if technical writing skills take high-levels details, you should still explain these concisely and clearly to your audience. As a technical writer, you should come up with documents that are very clear, simple, and succinct. Sometimes, though, the results could just be the opposite.

One of your greatest challenges as a technical writer is to transform complex information into an accessible and digestible document. To help you out, here are some technical writing tips you can apply to your work:

Before writing, think about your target audience The greatest challenge of technical writing is to write for your target audience. Because of this, there is a need to define the audience in the document’s planning process then consider this audience in each step of your writing process. When you have identified your audience, go a step further by coming up with a persona for such an audience and imagine that this exact person will be the one reading your document.
When you choose examples, think about them carefully first Keep in mind that each technical writing sample you may encounter might not be a good example. You might even want to consider some of these documents as illustrations of what you shouldn’t do instead of the guidelines for what you should do. At one point in your life, you may have bought an item that you needed to assemble and find out later that the instructions were not sufficient or were too confusing. This is a perfect example of poor technical writing. It is a good practice to review any sample document that you plan to use and make sure that the writing style and quality of information are good enough to serve the document’s intended purpose.
Use global English Since English is an international language. Therefore, writing technical documents in this language allows access of your document by a broader audience. Also, consider that many readers will be non-native speakers. To accommodate the largest audience possible, use global English. This English style is both literal and logical which makes it easier to understand. Furthermore, it overlaps with the principles of technical writing in terms of clarity and precision. Writing globally means you’re aware of the contents of your document which can be a challenge to comprehend or simply misunderstood.

More Templates

Newspaper Templates

All About Me Templates

Plot Diagram Templates

Essay Outline Templates

Table of Contents Templates

Envelope Address Templates

The Whatfix Blog | Drive Digital Adoption

CIO CIO CIO Blog Explore all new CIO, change, and ITSM content on our enterprise digitalization blog hub. Explore by Category Business Processes Change Management Digital Adoption Digital Transformation ERP Healthcare Transformation ITSM Insurance Transformation Procurement
Employee Experience Employee Experience EX Blog Explore all new employee experience related content on our EX blog hub. Explore by category Employee Onboarding Employee Training HCM HR & People Ops Instructional Design Learning Technology Performance Support Skill Development CRM Sales Ops
CX & Product Product CX & Product Ops Blog Explore all new CX and product-related content on our CX and product manager hub. Explore by category Product Ops Support Technical Documentation User Feedback User Onboarding
Resources Customer Experience What Is a Digital Adoption Platform? Learn how DAPs enable technology users in our ultimate guide. Resources Case Studies eBooks Podcasts White Papers
Explore Whatfix What Is Whatfix? Whatfix DAP Create contextual in-app guidance in the flow of work with Whatfix DAP. Mirror Easily create simulated application experiences for hands-on IT training with Whatfix Mirror. Product Analytics Analyze how users engage with desktop and web apps with no-code event tracking. Resources About Us Pricing Userization Whatfix AI
Back to Blog
Technical Documentation

11 Technical Writing Examples & Samples in 2024

Published: October 21, 2021
Updated: January 23, 2024

For any organization, there is a need for technical writers to provide easy-to-understand technical documentation to help explain complex processes for its products end-users, customers, and internal workforce.

Many organizations are a renewed focus on developing the technical writing skills of their writers and product managers. According to the U.S. Department of Labour Statistics, employment for technical content writing is expected to grow at a 12% faster rate between 2020-2030 in comparison to the overall average of other writing occupations.

With different industries having various technical writing needs (ie. in format types, tone, complexity, etc.), analyzing industry-leading technical writing examples from other companies can provide a roadmap and inspiration for new technical writers.

What Are Common Examples of Technical Writing?

User Manuals
Software Installation Guides
Standard Operating Procedures (SOP)
API Documentation
Service Level Agreements (SLA)
Press Release
Case Studies & White Papers
Company Documents
Requests for Proposals
Annual Reports
Business Plans

What Is Technical Writing?

Technical writing is a niche, user-centric form of writing used to disseminate information on technical or specialized topics, such as software applications, environmental regulations, or medical procedures. This writing style simplifies complex information and processes, allowing readers to use that information for an intended purpose – such as using technology, executing a project, onboarding a user, exemplifying a complex process, or informing a large audience.

Types of Technical Writing

Technical writing majorly falls into fourr categories:

1. End-User Technical Writing

End-user documentation aims to empower the user of a product by helping them understand the core functionality of a product and how to solve common troubleshooting issues. This form of writing is observed in types of technical documentation such as user manuals, legal disclaimers, employee handbooks, and website help centers.

2. Expert-to-Expert Technical Writing

A niche style of technical writing, this documentation includes types such as research summaries, legal documents, and white papers. These technical writing examples are written by experts, for experts, to help them dive deeper into a complex, industry-specific topic.

3. Process Documentation Writing

Process documentation is a form of technical writing that is designed for internal use by organizations to share knowledge on how to complete a task, with an emphasis on creating consistent, company-wide procedures. Examples of this type of technical writing include step-by-step process guides, internal wikis, KPI and goal reporting, OKRs, and HR policies.

4. Technical Marketing Communications

Most technical marketing communications fall under the B2B (business to business) writing umbrella. A technical writer needs to communicate their expertise in user-friendly language to help drive brand awareness and help prospective customers understand the product’s core benefits. Examples of companies using technical marketing writing include competitive analysis documents, in-depth case studies, marketing landing pages , informative articles, and business emails to promote or sell their services and products.

technical-writing-examples-process-chart

What’s the Difference Between Business Writing & Technical Writing?

Technical writing is often confused with business writing. Although both writing styles share similarities, writers can’t use them interchangeably. Both writing styles adhere to formal, specific, and concise language to convey the intent. There is an additional use of bulleted and numbered lists for an easier-to-read content structure.

Technical writing maintains a neutral, competent tone throughout its documentation, as the sole purpose of technical writing is to clearly explain complex topics to a non-technical reader. However, in business writing, the tone varies depending on the target reader. For example, a proposal requires persuasive language to highlight the factual aspects of a bid, while an external email to a new client requires a professional, yet warm tone.

PRO TIP : To decide the writing style, answer a simple question. Is my writing intended to communicate the desired purpose or an instruction?

11 Examples of Technical Writing in 2024

Here are 11 examples of common technical writing documents – with real-world samples for you to use as inspiration for your business’s technical writing needs.

1. User Manuals

User guides are instruction training manuals written for novice end-users to help them with products ranging from consumer products such as electronics or appliances to B2B SaaS tools and solutions. These manuals are user-friendly and well-illustrated to highlight common issues and features.

Additionally, technical writers must collaborate with engineers, programmers, and product designers to cover all the bases.

2. Software Installation Guides

Computer software must be equipped with software documentation , such as installation guides, to assist users through the software implementation and installation process.

A well-written installation guide must include detailed workflows, video tutorials, FAQs, and a troubleshooting guide. Often the programmers automate the process, and the technical writer authors alert boxes and the ReadMe file.

Software installation guides can be easily created, published, and maintained with software documentation tools .

3. Standard Operating Procedures (SOP)

Standard operating procedures (SOPs) are holistic processes to help employees work in unison and accomplish various tasks in an organization. SOPs are a form of process documentation that ensures smoother internal operations and workflows by making business processes more efficient and economical. Examples of an SOP document include anything from payroll processing to manufacturing guidelines.

4. API Documentation

API documentation helps your customers’ developers interact easily with a product’s code to implement an API effectively. It contains instructions and tutorials to simplify integration with other APIs such as web-API, software API, and SCPIs.

5. Service Level Agreements (SLA)

An SLA is a legally binding contract between a provider and a customer that outlines services, guarantees, warranties, and other mutually negotiated items between the two parties.

Source: BMC

6. Press Releases

Press releases are formal and factual documents issued by an organization to make business-related announcements.

They are short and factual documents that highlight how the announcement impacts users and external stakeholders of the organization. This technical document has a specific format and includes a headline, overview of the information, company’s contact information, and direct quotes from internal stakeholders like the CEO.

Source: Apple

7. Case Studies & Whitepapers

Case studies & whitepapers are industry-specific documents that provide real-world examples testifying to an organization’s expertise and value, and are used for lead generation purposes.

Case studies are instance-specific documents written in passive voice and offer key takeaways, often using data to highlight its benefits. In comparison, whitepapers address a specific challenge and are written in an active voice. Technical writers authoring such documents should possess in-depth knowledge about the industry for effective writing.

Source: Whatfix

8. Company Documents

Company HR documents such as employee handbooks and orientation manuals require a perfect combination of technical writing skills and organizational knowledge. These documents are of immense help during the initial phases of employee onboarding and provide continuous support for ongoing employee development and general assistance.

blissbook-tool-for-creating-company-handbooks

9. Request for Proposal (RFP)

An RFP is a business document that announces a project and solicits bids from multiple qualifying contractors. The writing style of this document is persuasive, and a poorly-written RFP document can ensure whether or not the deal will be successful. A well-written RFP must clearly highlight the project goals, challenges, scope of work, and evaluation metrics.

Source: Venngage

10. Annual Reports

Annual reports are exhaustive documents that indicate a company’s financial health and yearly performance. These reports are of prime importance to the organizations seeking investors’ trust and include stock performance, financial information, new product information, and strategic developments.

Source: Tesla

11. Business Plans

Every organization starts with a detailed business plan to secure funding and requires an update during expansion phases. A business plan must include the following sections:

Executive Summary: This section provides an overview of the business plan, target market, and purpose.
Product Description: The product or service description includes a brief about the offering, its USP, and the development stage.
SWOT Analysis: A complete analysis of strengths, weaknesses, opportunities, and threats for the business.
Market Research: This section includes a detailed analysis of all the competitors and product potential in the target market.
Organizational System: Before the initial start-up, it is crucial to clarify the organizational hierarchy and team members to support the business.
Schedule: This section highlights the implementation schedule and includes start date, hiring, and investment milestones.
Financial Planning: This is the most critical section and highlights the viability of the business plan. It includes income statements, projected revenues, balance sheets, and liquidity measures.
Appendix: The appendix consists of any other additional and relevant information such as patents.

Create contextual user onboarding flows, drive adoption of new features, and make in-app announcements with Whatfix

Whatfix is a no-code digital adoption platform that enables product managers to create contextual in-app guidance, product-led user onboarding, and self-help user support – all without engineering dependencies. With Whatfix, create branded product tours, user onboarding checklists, interactive walkthroughs, pop-ups, smart tips, and more – all enabling customers and users with contextual guidance at the moment need. With Whatfix, analyze, build, and deliver better user experiences.

Technical writing is an analytical form of writing where attention to detail is paramount. Unlike creative writing, technical writing doesn’t need to invoke the reader’s emotions – but instead, its goal is to convey complex information in an easy-to-read, digestible form.

Technical writing doesn’t negate creativity. It’s a subtle form of writing which needs to be highly user-centric and understandable.

Technical writing tools such as Whatfix help you author impactful technical documents in a way that encourages interaction and retention. With Whatfix, technical writers create on-screen guides, pop-up prompts, tooltips, chatbots, in-app knowledge bases, and more to inform users how to use your product. A technical writer’s goal should be to create documents that promote your product effectively and to make those documents easy and fun to read.

Learn how Whatfix can help create the interactive product and process walkthroughs you need now!

What is Technical Writing? A Comprehensive Overview

Carla Wardin

Senior Marketing Communications Consultant

Illustration of a technical writing checklist with a blue pen and gears in the background, symbolizing the structured and detailed nature of technical documentation.

Why technical writing matters, differentiating technical writing from other forms, skills for technical writers, choosing the right tools for your technical writing projects, technical writing processes and techniques, the importance of visual elements, types of technical documents, working with smes, handling technical reviews and feedback, the role of technical editing, career paths in technical writing, gaining relevant experience as a technical writer, translating technical knowledge into words and visuals, subscribe to techsmith’s newsletter.

Have you ever struggled to understand a complicated manual or wished a set of instructions were clearer? That’s where the magic of technical writing comes in. Technical writing is the art of translating complex information into easy-to-understand documentation.

In this post, we’ll explore what technical writing is, why it’s important, and the skills required to do it well. Whether you’re considering a career in technical writing or simply curious about the process, this guide is for you.

Technical writing plays a pivotal role in many aspects of our lives and different industries. Here’s why good technical writing is so important:

It helps users understand and use products more effectively
It saves time by providing precise instructions
Reduces the need for customer support
Ensures procedures are followed correctly
Improves the overall user experience

Technical writing is different from other forms of writing.

While other forms of writing may aim to entertain, inspire, or express opinions to readers, technical writing focuses on instructing. It targets specific audiences with varying levels of technical knowledge and uses clear, concise, and objective language.

Technical writing is highly structured and often includes visual aids to help with understanding, while other forms of writing are free-flowing and use visuals for aesthetic purposes.

While strong writing skills are a given, other qualities that good technical writers employ include clarity, accuracy, conciseness, and usability.

Writing and Communication

Technical writers need to focus on straightforward language and avoid opinion, jargon, and complex wording. Writers can take courses designed for technical writing to learn strategies. Technical writers need to express information efficiently, eliminating unnecessary words and phrases. Writers can edit their work, removing redundancies and wordiness.

It does take time to simplify. A lot of times, I’ll write out what I think, and then I go back to it later, and it’s like I can take this out, and I can take this out, and this goes over here, and this goes over here, it’s a process. Michele Wiedemer, Customer Education Consultant 🎧 The Visual Lounge: Episode 13

Accuracy and attention to detail

Technical writers need to research and test their text since errors can negatively affect the readers. They can learn how to evaluate sources and identify credible information, as well as work with reviewers to catch errors.

Organizational skills

Technical writing involves thoughtful organization, clear instructions, and a user-centric approach.

Selecting the right tools for your technical writing projects depends on several factors, like your project requirements, budget, collaboration goals, and integration with what you’re already using. Technical writers use a variety of tools, including version control systems and content management systems. However, two tools from TechSmith stand out:

Snagit for screen capture and simple recordings

This screen capture and image editing tool works well for technical writing needs. It allows you to capture screenshots, annotate images with arrows, callouts, and text, and create step-by-step visual guides .

Snagit’s scrolling capture feature is particularly useful for documenting long web pages or software interfaces. Snagit’s presets and custom hotkeys let you create presets for your most-used tasks, like capturing a specific area of your screen or applying a particular set of annotations. Really, that’s just the beginning. See why technical writers choose Snagit.

Annotate and edit screenshots with Snagit

Professional mark-up tools and powerful features make it easy to create helpful images.

Screenshot of a document about puffin migration patterns with a section for changing styles highlighted.

Camtasia for polished training videos

Camtasia is an all-in-one screen recording and video editing software that lets technical writers create professional-quality video tutorials and demonstrations. With drag-and-drop transitions, callouts, and more, you don’t have to be a professional video editor to get impressive results.

Creating useful technical documentation is a process that involves careful planning.

First, you’ll need to plan by defining your audience, establishing the purpose of the document, and deciding the scope of the project.
Next is research, where you gather information and organize it into an outline or flowchart that works for you.
For the writing portion, you’ll have to draft your content, following the outline and using the research findings.
You’ll also want to incorporate visuals like diagrams and annotated screenshots to make your content easier to understand.
After that, there’s the review and revision process.

Visual elements are helpful for creating effective technical documentation. They can help to:

Clarify complex information: Annotated visuals can illustrate complex concepts in a way that is easier to understand than text alone.
Break up long blocks of text: Visuals can make your document more visually appealing and less intimidating.
Improve engagement: Engaging visuals can help to keep readers interested in your content.

By following these steps, you can create clear, concise, and informative technical documents.

Technical writers create many different kinds of documents , each serving a specific purpose and tailored to a particular audience. Let’s explore some of the most common types of technical documents and look at tips for writing them.

User manuals

User manuals are guides designed to help users understand and use a product or service. Tailor your language and level of detail to the user’s technical expertise. Avoid technical terms whenever possible, and use screenshots, diagrams, and other visuals to illustrate instructions and clarify complex concepts.

Standard operating procedures (SOPs)

SOPs are detailed, step-by-step instructions for performing specific tasks or processes. They are designed to help with consistency, quality, and safety in workplace operations. In writing these, it helps to be specific and detailed, so there’s no room for interpretation. Use flowcharts, diagrams, or photos to illustrate the process and keep them up-to-date.

White papers

White papers are reports that explore a specific topic or problem in depth. They are used to educate readers, present research findings, or promote a particular product or service. Gather information from credible sources, cite your references, and focus on presenting information and insights, not selling a product or service.

Case studies

Case studies examine real-world scenarios or projects. A good strategy is to highlight the solution’s measurable benefits and create a narrative that highlights key statistics.

Technical writers typically work with subject matter experts , also known as SMEs, who have invaluable technical expertise about the product. Collaboration between SMEs and technical writers is critical for producing the best quality documentation.

Before meeting with an SME, research the topic and prepare a list of questions that focus on the information you need for your document. You can also ask questions during the interview.

It’s important to establish a relationship with your SMEs since you will be working with them on a regular basis. Don’t hesitate to ask SMEs to explain technical terms or concepts in simpler language. This will help you translate their knowledge into clear writing your target audience can understand.

To capture accurate information, take detailed notes as well as record interviews for future reference. It’s also helpful to check the information you receive from SMEs with other sources.

Technical reviews are part of the writing process, as they let SMEs check documents for accuracy. Approach feedback with an open mind since SMEs are experts in their field, and their changes can help you improve the quality of your documentation. Consider all changes and incorporate them as appropriate. Be sure to track changes so you can easily identify revisions and share the revised document with your SME.

By following these strategies for effective collaboration and feedback management, you can build relationships with SMEs and produce high-quality technical documentation that meets your audience’s needs.

The best snipping tool for Windows and Mac

Don’t let clumsy built-in tools hold you back. Take and edit screenshots with Snagit!

Someone capturing a screenshot of a mountain scene with a person and goats using Snagit, showing cropping tools on the screen.

Technical editing is another quality control checkpoint for your documentation. Technical editors, often experienced writers themselves, review your content for accuracy, clarity, consistency, and usability. Technical editors also catch grammatical errors, typos, and formatting errors, making sure the final product is polished and professional.

While a professional technical editor is invaluable, self-editing and peer reviews are also important steps. After checking your own work with fresh eyes, find someone with technical knowledge or experience in your field to look it over. Let the reviewer know what type of feedback you’re looking for, such as clarity, accuracy, and usability.

Technical writing offers many career paths with opportunities for specialization in different industries and types of documents. Types of specialization include API, medical, scientific, and UX. After gaining experience and expertise, technical writers can advance to roles such as technical writing manager, content strategist, or technical communication consultant.

Gaining experience in your chosen profession takes some work. You can start with internships and freelance work to build your exposure and reputation in the industry. Networking with other technical writers and potential employers also helps – go to industry events and conferences to connect. Professional development opportunities like online courses will also help you learn more about – and keep up with – changes in technical writing.

Technical writers are skilled at simplifying technical jargon, creating engaging content, and using tools to help them reach their audiences. By following a structured writing process, collaborating with subject matter experts, and continuing to learn, technical writers can work in a wide range of industries. Translating technical knowledge into easily understood content is a talent that will always be in demand.

Speed up your screenshot workflows

Stop wasting your time with built-in snipping tools, and try Snagit!

Additional Resources

How to remove the background from an image, how to blur text in screenshots: 5 tips for clear, private screenshots, how to screen record on windows 10 or 11 (with audio).

Writing Instructions

One of the most common and important uses of technical writing is instructions—those step-by-step explanations of how to do things: assemble something, operate something, repair something, or explain a personal process (enrolling in college, for example) so that readers may better understand it and possibly use it themselves.

Process texts are extremely common in school and professions. In school, teachers frequently assign process assignments. For example, humanities professors may ask for a description of how an artistic or literary period evolved; history professors, the contributions of a culture’s leaders over time; social science professors, the chronology of inventions; engineering professors, explanations of how sound is changed into electrical signals; business professors, how the Federal Reserve works or how to sell a product.

On a daily basis, we read descriptive processes, including recipes, user manuals for new software, or advice columns on how to lose weight or how to succeed in school or a profession. These texts focus on answering one of the following questions:

“How is this done?”
“How can I do this?”

While the topics of a process report or a set of instructions may vary, many share similarities: most are written to explain how something works, most are structured in chronological order using numbered steps, and most rely extensively on visuals . In writing instructions for learning a new software program, for example, writers might use screenshots and/or screen videos to walk users through the tutorial.

Generally, it is good to have both text and visuals in your instructions since your audience is likely comprised of people with different learning styles. However, the use of visuals can vary depending on your audience and the intended use of the instructions. Visuals help to clarify a concept that is difficult to explain using only words. Graphics may be used to show how something looks, how something should look once the step has been completed, how something is done or constructed, show trends or relationships, add liveliness to the project, or simply help to organize information. Graphics are useful since almost everyone (including children and others of a different language) can understand visual instructions and see exactly what they need to complete.

Types of Instructions

There are three main types of process texts:

Descriptive processes : these answer the question, “How is this done?” These texts describe how a process occurs so that readers can understand it better. For example, writing a descriptive process about how you registered for a course online rather than in person might be useful to someone who has never done online registration.
Prescriptive processes : these are explanatory in nature; they prescribe how something is done (or should be done) so that readers can do it themselves. These are the most common type of instructional documents. For example, you might write a prescriptive process guide for users explaining how to perform basic maintenance on their cars, such as changing their own oil, checking spark plugs, or replacing brake pads. *The samples listed below are examples of prescriptive processes.
Blended descriptive and prescriptive processes make the main thrust of the document a descriptive process while having a few sections summarizing how the readers can perform the process. In other words, writers may address both “How can I do this?” and “How is this done?” in different parts of one text. Alternatively, they might develop different versions of the same document for two audiences–an audience of users and an audience of interested parties.

Getting Started

At the beginning of an instruction-writing project or assignment, it’s important to consider your audience and determine the characteristics (the number of tasks and steps) of the particular procedure you intend to write about.

Audience and situatio n: Early in the process, define the audience and situation of your instructions. Remember that defining an audience means defining its level of knowledge and familiarity with the topic. It is sometimes helpful to describe your audience to yourself first, and then use that to assess your message at the end to be certain it’s appropriate for your audience.

Number of tasks : An important consideration is how many tasks there are in the procedure for which you are writing instructions. The term procedure can be used to refer to the whole set of activities your instructions discuss, while task can be used to define a semi-independent group of actions within the procedure. For example, setting up your modem is one task in the overall procedure of connecting a computer to the internet.

As another example, a simple procedure like changing a car’s oil contains only one task; there are no semi-independent groupings of other activities. A more complex procedure, like using a microwave oven, contains plenty of semi-independent tasks, such as setting the clock, setting the power level, using the timer, cleaning and maintaining the microwave, and more.

Some instructions have only a single task but have many steps within that single task. For example, imagine a set of instructions for assembling a children’s swing set. One effective approach would be to group similar and related steps into phases , and then renumber the steps at each new phase. A phase is a group of similar steps within a single-task procedure. In the swing set example, setting up the frame would be one phase; anchoring the thing in the ground would be another; and assembling the box swing would be still another.

Focusing Instructions

Another consideration, which maybe you can’t determine early on, is how to focus your instructions. For most instructions, you can focus on the tasks involved , or you can focus on the tools needed .

In a task approach to instructions on using a phone-answering machine, you’d have sections on recording your greeting, playing back your messages, saving your messages, forwarding your messages, and deleting your messages. These are tasks—the typical things users would want to do with the machine.
On the other hand, in a tools approach to instructions on using a photocopier, there would be sections on the copy button, the cancel button, the enlarge/reduce button, the collate/staple button, the paper tray, the copy-size button, and so on. If you designed a set of instructions on this plan, you’d likely write steps for using each button or feature of the photocopier.

Instructions Content

Be sure to read the section on “ Document Design ” before creating your instructions. Include the following items:

Introduction : In carefully planning your instructions’ introduction, be sure to:

Indicate the specific tasks or procedure to be explained.
Indicate what the audience needs in terms of knowledge and background to understand the instructions.
Give a general idea of the procedure and what it accomplishes.
Indicate the conditions when these instructions should (or should not) be used.
Give an overview of the contents of the instructions.

General warning, caution, danger notice s: Instructions must also alert readers to the possibility of ruining their equipment, screwing up the procedure, and/or hurting themselves. Also, instructions must emphasize key points or exceptions. For these situations, you should use special notices , such as Note , Warning , Caution , and/or Danger .

Technical background or theory: At the beginning of some instructions (usually after the introduction), you may need a discussion of background related to the procedure. For certain instructions, this background is critical—otherwise, the steps in the procedure make no sense. In some cases, writers of instructions may need to spend significant time explaining things to readers before moving on to the actual steps involved in the process.

Equipment and supplies : Most instructions include a list of the things you need to gather before you start the procedure. This includes equipment , the tools you use in the procedure (such as mixing bowls, spoons, bread pans, hammers, drills, and saws) and supplies , the things that are consumed in the procedure (such as wood, paint, oil, flour, and nails). In instructions, these are typically listed either in a simple vertical list or in a two-column list at the start of the instructions. Use the two-column list if you need to add specifications to some or all of the items—for example, brand names, sizes, amounts, types, model numbers, and so on.

Discussion of the steps : When you get to the actual writing of the steps be certain to carefully consider the structure and format of those steps, any supplementary information that might be needed, and the point of view and general writing style of the instructions. One point of view used in technical writing is the second person, which is addressing the audience as you .

*Generally speaking, writers of instructions should strive to do the following:

Use clear, simple writing whenever possible.
Have a thorough understanding of the process in all its technical detail.
Work toward putting yourself in the place of the reader who will be using your instructions.

Student instruction samples

Welding Instructions Sample (student sample)
Mechatronics Instructions Sample – Testing Diodes & Transistors (student sample)
Auto/Diesel Instructions – How to Replace A Rear Sway Bar on A Toyota Corolla (student sample)
Assembling A PC (student sample)
How to Change Guitar Strings (student sample)

Professional instruction samples

Welding Instructions Sample 1 (professional sample)
Barbie Dreamhouse (professional sample)
Trampoline Assembly (professional sample)

Additional Resources

“ Writing Instructions , ” Technical Writing Essentials
“ Instructions ” Online Technical Writing

"Instructions & Process Reports." . [License: CC: BY-SA 4.0] "Instructions." . [License: CC: BY-SA 4.0] Figure 4.1.1: Alex, Mihis. . Figure 4.1.2: Chung, Abby.

Share This Book

8 Technical Writing Examples to Inspire You

Become a Certified Technical Writer

As a technical writer, you may end up being confused about your job description because each industry and organization can have varying duties for you. At times, they may ask for something you’ve never written before. In that case, you can consider checking out some technical writing examples to get you started.

If you’re beginning your technical writing career, it’s advisable to go over several technical writing examples to make sure you get the hang of it. You don’t necessarily have to take a gander over at industry-specific examples; you can get the general idea in any case.

This article will go over what technical writing is and some of the common technical writing examples to get you started. If you’re looking to see some examples via video, watch below. Otherwise, skip ahead.

If you’re looking to learn via video, watch below. Otherwise, skip ahead.

Let’s start by covering what technical writing is .

What Exactly is Technical Writing?

Technical writing is all about easily digestible content regarding a specialized product or service for the public. Technical writers have to translate complex technical information into useful and easy-to-understand language.

There are many examples of technical writing, such as preparing instruction manuals and writing complete guides. In some cases, technical writing includes preparing research journals, writing support documents, and other technical documentation.

The idea is to help the final user understand any technical aspects of the product or service.

In other cases, technical writing means that the writer needs to know something. For example, pharmaceutical companies may hire medical writers to write their content since they have the required knowledge.

If you’re interested in learning more about these technical writing skills, then check out our Technical Writing Certification Course.

8 Technical Writing Examples to Get You Started

As a technical writer, you may have to learn new things continually, increase your knowledge, and work with new forms of content. While you may not have experience with all forms of technical writing, it’s crucial to understand how to do it.

If you learn all the intricacies of technical writing and technical documents, you can practically work with any form of content, given that you know the format.

Therefore, the following examples of technical writing should be sufficient for you to get an idea. The different types of technical writing have unique characteristics that you can easily learn and master effectively.

1. User Manuals

User manuals or instruction manuals come with various products, such as consumer electronics like televisions, consoles, cellphones, kitchen appliances, and more. The user manual serves as a complete guide on how to use the product, maintain it, clean it, and more. All technical manuals, including user manuals, have to be highly user-friendly. The technical writer has to write a manual to even someone with zero experience can use the product. Therefore, the target audience of user manuals is complete novices, amateurs, and people using the product/s for the first time.

Traditionally, user manuals have had text and diagrams to help users understand. However, user manuals have photographs, numbered diagrams, disclaimers, flow charts, sequenced instructions, warranty information, troubleshooting guides, and contact information in recent times.

Technical writers have to work with engineers, programmers, and product designers to ensure they don’t miss anything. The writer also anticipates potential issues ordinary users may have by first using the product. That helps them develop a first-hand experience and, ultimately, develop better user manuals.

The point of the user manual isn’t to predict every possible issue or problem. Most issues are unpredictable and are better handled by the customer support or help desk. User manuals are there to address direct and common issues at most.

You can check out some user manual examples and templates here . You can download them in PDF and edit them to develop an idea about how you can write a custom user manual for your product.

2. Standard Operating Procedures (SOP)

Standard operating procedures are complete processes for each organization’s various tasks to ensure smoother operations. SOPs help make each process more efficient, time-saving, and less costly.

An SOP document can include:

Everything from the method of processing payroll.
Hiring employees.
Calculating vacation time to manufacturing guidelines.

In any case, SOPs ensure that each person in an organization works in unison and uniformly to maintain quality.

SOPs help eliminate irregularities, favoritism, and other human errors if used correctly. Lastly, SOPs make sure employees can take the responsibilities of an absent employee, so there’s no lag in work.

Therefore, developing SOPs requires a complete study of how an organization works and its processes.

Here are some examples of standard operating procedures you can study. You can edit the samples directly or develop your own while taking inspiration from them.

3. Case Studies & White Papers

Case studies and white papers are a way of demonstrating one’s expertise in an area. Case studies delve into a specific instance or project and have takeaways proving or disproving something. White papers delve into addressing any industry-specific challenge, issue, or problem.

Both case studies and white papers are used to get more business and leads by organizations.

Technical writers who write white papers and case studies need to be experts in the industry and the project itself. It’s best if the technical writer has prior experience in writing such white papers.

The writing style of white papers and case studies is unique, along with the formatting. Both documents are written for a specific target audience and require technical writing skills. Case studies are written in a passive voice, while white papers are written in an active voice. In any case, it’s crucial to maintain a certain level of knowledge to be able to pull it off.

You can check out multiple white paper examples here , along with various templates and guides. You can check out some examples here for case studies, along with complete templates.

4. API Documentation

API documentation includes instructions on effectively using and integrating with any API, such as web-API, software API, and SCPIs. API documentation contains details about classes, functions, arguments, and other information required to work with the API. It also includes examples and tutorials to help make integration easier.

In any case, API documentation helps clients understand how it works and how they can effectively implement API. In short, it helps businesses and people interact with the code more easily.

You can find a great example of proper API documentation in how Dropbox’s API documentation works. You can learn more about it here .

5. Press Releases

Press releases are formal documents issued by an organization or agency to share news or to make an announcement. The idea is to set a precedent for releasing any key piece of information in a follow-up press conference, news release, or on a social media channel.

The press release emphasizes why the information is important to the general public and customers. It’s a fact-based document and includes multiple direct quotes from major company stakeholders, such as the CEO.

Usually, press releases have a very specific writing process. Depending on the feasibility, they may have an executive summary or follow the universal press release format.

You can find several examples of press releases from major companies like Microsoft and Nestle here , along with some writing tips.

6. Company Documents

Company documents can include various internal documents and orientation manuals for new employees. These documents can contain different information depending on their use.

For example, orientation manuals include:

The company’s history.
Organizational chart.
List of services and products.
Map of the facility.
Dress codes.

It may also include employee rights, responsibilities, operation hours, rules, regulations, disciplinary processes, job descriptions, internal policies, safety procedures, educational opportunities, common forms, and more.

Writing company documents requires good technical writing skills and organizational knowledge. Such help files assist new employees in settling into the company and integrating more efficiently.

Here are some great examples of orientation manuals you can check out.

7. Annual Reports

Annual reports are yearly updates on a company’s performance and other financial information. Annual reports directly correspond with company stakeholders and serve as a transparency tool.

The annual reports can also be technical reports in some cases. However, mostly they include stock performance, financial information, new product information, and key developments.

Technical writers who develop annual reports must compile all the necessary information and present it in an attractive form. It’s crucial to use creative writing and excellent communication skills to ensure that the maximum amount of information appears clearly and completely.

If the company is technical, such as a robotics company, the technical writer needs to develop a technical communication method that’s easy to digest.

You can check out some annual report examples and templates here .

8. Business Plans

Every company starts with a complete business plan to develop a vision and secure funding. If a company is launching a new branch, it still needs to start with a business plan.

In any case, the business plan has a few predetermined sections. To develop the ideal business plan, include the following sections in it.

Executive Summary – includes the business concept, product, or service, along with the target market. It may also include information on key personnel, legal entity, founding date, location, and brief financial information.
Product or Service Description – includes what the offering is, what value it provides, and what stage of development it is in currently.
Team Members – includes all the information on the management team.
Competitor and Market Analysis – includes a detailed analysis of the target market and potential competitors.
Organizational System – includes information on how the organizational structure would work.
Schedules – include start dates, hiring dates, planning dates, and milestones.
Risks and Opportunities – include profit and loss predictions and projections.
Financial Planning – includes planned income statements, liquidity measures, projected balance sheet, and more.
Appendix – includes the organizational chart, resumes, patents, and more.

The technical writer needs to work closely with the company stakeholders to develop a complete business plan.

According to your industry, you can check out hundreds of business plan samples and examples here .

Becoming an Expert Technical Writer

Becoming an expert technical writer is all about focusing on your strengths. For example, you should try to focus on one to two industries or a specific form of technical writing. You can do various writing assignments and check out technical writing samples to understand what you’re good with.

You can also check out user guides and get online help in determining your industry. Once you’ve nailed down an industry and technical writing type, you can start to focus on becoming an expert in it.

In any case, it always helps to check out technical writing examples before starting any project. Try to check out examples of the same industry and from a similar company. Start your writing process once you have a complete idea of what you need to do.

Since technical writing involves dealing with complex information, the writer needs to have a solid base on the topic. That may require past experience, direct technical knowledge, or an ability to understand multiple pieces of information quickly and effectively.

In becoming a technical writer, you may have to work with various other people, such as software developers, software engineers, human resources professionals, product designers, and other subject matter experts.

While most organizations tend to hire writers with a history in their fields, others opt for individuals with great writing skills and team them up with their employees.

Technical writers may also work with customer service experts, product liability specialists, and user experience professionals to improve the end-user experience. In any case, they work closely with people to develop digestible content for the end customers.

Today, you can also find several technical writers online. There is an increasing demand for technical writing because of the insurgence of SaaS companies, e-commerce stores, and more.

In the end, technical writers need to have a strong grasp of proper grammar, terminology, the product, and images, graphics, sounds, or videos to explain documentation.

If you are new to technical writing and are looking to break-in, we recommend taking our Technical Writing Certification Course , where you will learn the fundamentals of being a technical writer, how to dominate technical writer interviews, and how to stand out as a technical writing candidate.

We offer a wide variety of programs and courses built on adaptive curriculum and led by leading industry experts.

Work on projects in a collaborative setting
Take advantage of our flexible plans and community
Get access to experts, templates, and exclusive events

Become a Certified Technical Writer. Professionals finish the training with a full understanding of how to guide technical writer projects using documentation foundations, how to lead writing teams, and more.

Become a Certified UX Writer. You'll learn how to excel on the job with writing microcopy, content design, and creating conversation chatbots.

Become a Certified Grant Writer. In this course, we teach the fundamentals of grant writing, how to create great grant proposals, and how to stand out in the recruiting process to land grant writing jobs.

Please check your email for a confirmation message shortly.

Join 5000+ Technical Writers

Get our #1 industry rated weekly technical writing reads newsletter.

Your syllabus has been sent to your email

Technical Writing for Beginners – An A-Z Guide to Tech Blogging Basics

If you love writing and technology, technical writing could be a suitable career for you. It's also something else you can do if you love tech but don’t really fancy coding all day long.

Technical writing might also be for you if you love learning by teaching others, contributing to open source projects and teaching others how to do so, too, or basically enjoy explaining complex concepts in simple ways through your writing.

Let's dive into the fundamentals and learn about what you should know and consider when getting started with technical writing.

In this article, we’ll be looking at:

What Technical writing is

Benefits of Technical Writing

Necessary skills to have as a Technical Writer

The Technical Writing Process

Platforms for publishing your articles

Technical Writing Courses

Technical Writing forums and communities
Some amazing technical writers to follow
Final Words and references

What is Technical Writing?

Technical writing is the art of providing detail-oriented instruction to help users understand a specific skill or product.

And a technical writer is someone who writes these instructions, otherwise known as technical documentation or tutorials. This could include user manuals, online support articles, or internal docs for coders/API developers.

A technical writer communicates in a way that presents technical information so that the reader can use that information for an intended purpose.

Technical writers are lifelong learners. Since the job involves communicating complex concepts in simple and straightforward terms, you must be well-versed in the field you're writing about. Or be willing to learn about it.

This is great, because with each new technical document you research and write, you will become an expert on that subject.

Technical writing also gives you a better sense of user empathy. It helps you pay more attention to what the readers or users of a product feel rather than what you think.

You can also make money as a technical writer by contributing to organizations. Here are some organizations that pay you to write for them , like Smashing Magazine , AuthO , Twilio , and Stack Overflow .

In addition to all this, you can contribute to Open Source communities and participate in paid open source programs like Google Season of Docs and Outreachy .

You can also take up technical writing as a full time profession – lots of companies need someone with those skills.

Necessary Skills to Have as a Technical Writer

Understand the use of proper english.

Before you consider writing, it is necessary to have a good grasp of English, its tenses, spellings and basic grammar. Your readers don't want to read an article riddled with incorrect grammar and poor word choices.

Know how to explain things clearly and simply

Knowing how to implement a feature doesn't necessarily mean you can clearly communicate the process to others.

In order to be a good teacher, you have to be empathetic, with the ability to teach or describe terms in ways suitable for your intended audience.

If you can't explain it to a six year old, you don't understand it yourself. Albert Einstein

Possess some writing skills‌‌

I believe that writers are made, not born. And you can only learn how to write by actually writing.

You might never know you have it in you to write until you put pen to paper. And there's only one way to know if you have some writing skills, and that's by writing.

So I encourage you to start writing today. You can choose to start with any of the platforms I listed in this section to stretch your writing muscles.

And of course, it is also a huge benefit to have some experience in a technical field.

Analyze and Understand who your Readers are

The biggest factor to consider when you're writing a technical article is your intended/expected audience. It should always be at the forefront of your mind.

A good technical writer writes based on the reader’s context. As an example , let's say you're writing an article targeted at beginners. It is important not to assume that they already know certain concepts.

You can start out your article by outlining any necessary prerequisites. This will make sure that your readers have (or can acquire) the knowledge they need before diving right into your article.

You can also include links to useful resources so your readers can get the information they need with just a click.

In order to know for whom you are writing, you have to gather as much information as possible about who will use the document.

It is important to know if your audience has expertise in the field, if the topic is totally new to them, or if they fall somewhere in between.

Your readers will also have their own expectations and needs. You must determine what the reader is looking for when they begin to read the document and what they'll get out of it.

To understand your reader, ask yourself the following questions before you start writing:

Who are my readers?
What do they need?
Where will they be reading?
When will they be reading?
Why will they be reading?
How will they be reading?

These questions also help you think about your reader's experience while reading your writing, which we'll talk about more now.

Think About User Experience

User experience is just as important in a technical document as it is anywhere on the web.

Now that you know your audience and their needs, keep in mind how the document itself services their needs. It’s so easy to ignore how the reader will actually use the document.

As you write, continuously step back and view the document as if you're the reader. Ask yourself: Is it accessible? How will your readers be using it? When will they be using it? Is it easy to navigate?

The goal is to write a document that is both useful to and useable by your readers.

Plan Your Document

Bearing in mind who your users are, you can then conceptualize and plan out your document.

This process includes a number of steps, which we'll go over now.

Conduct thorough research about the topic

While planning out your document, you have to research the topic you're writing about. There are tons of resources only a Google search away for you to consume and get deeper insights from.

Don't be tempted to lift off other people's works or articles and pass it off as your own, as this is plagiarism. Rather, use these resources as references and ideas for your work.

Google as much as possible, get facts and figures from research journals, books or news, and gather as much information as you can about your topic. Then you can start making an outline.

Make an outline

Outlining the content of your document before expanding on it helps you write in a more focused way. It also lets you organize your thoughts and achieving your goals for your writing.

An outline can also help you identify what you want your readers to get out of the document. And finally, it establishes a timeline for completing your writing.

Get relevant graphics/images

Having an outline is very helpful in identifying the various virtual aids (infographics, gifs, videos, tweets) you'll need to embed in different sections of your document.

And it'll make your writing process much easier if you keep these relevant graphics handy.

Write in the Correct Style

Finally, you can start to write! If you've completed all these steps, writing should become a lot easier. But you still need to make sure your writing style is suitable for a technical document.

The writing needs to be accessible, direct, and professional. Flowery or emotional text is not welcome in a technical document. To help you maintain this style, here are some key characteristics you should cultivate.

Use Active Voice

It's a good idea to use active voices in your articles, as it is easier to read and understand than the passive voice.

Active voice means that the subject of the sentence is the one actively performing the action of the verb. Passive voice means that a subject is the recipient of a verb's action .

Here's an example of passive voice : The documentation should be read six times a year by every web developer.

And here's an example of active voice : Every web developer should read this documentation 6 times a year.

Choose Your Words Carefully

Word choice is important. Make sure you use the best word for the context. Avoid overusing pronouns such as ‘it’ and ‘this’ as the reader may have difficulty identifying which nouns they refer to.

Also avoid slang and vulgar language – remember you're writing for a wider audience whose disposition and cultural inclinations could differ from yours.

Avoid Excessive Jargon

If you’re an expert in your field, it can be easy to use jargon you're familiar with without realizing that it may be confusing to other readers.

You should also avoid using acronyms you haven't previously explained.

Here's an Example :

Less clear: PWAs are truly considered the future of multi-platform development. Their availability on both Android and iOS makes them the app of the future.

Improved: Progressive Web Applications (PWAs) are truly the future of multi-platform development. Their availability on both Android and iOS makes PWAs the app of the future.

Use Plain Language

Use fewer words and write in a way so that any reader can understand the text.‌‌ Avoid big lengthy words. Always try to explain concepts and terms in the clearest way possible.

Visual Formatting

A wall of text is difficult to read. Even the clearest instructions can be lost in a document that has poor visual representation.

They say a picture is worth a thousand words. This rings true even in technical writing.

But not just any image is worthy of a technical document. Technical information can be difficult to convey in text alone. A well-placed image or diagram can clarify your explanation.

People also love visuals, so it helps to insert them at the right spots. Consider the images below:

First, here's a blog snippet without visuals:

Here's a snippet of same blog, but with visuals:

Adding images to your articles makes the content more relatable and easier to understand. In addition to images, you can also use gifs, emoji, embeds (social media, code) and code snippets where necessary.

Thoughtful formatting, templates, and images or diagrams will also make your text more helpful to your readers. You can check out the references below for a technical writing template from @Bolajiayodeji.

Do a Careful Review

Good writing of any type must be free from spelling and grammatical errors. These errors might seem obvious, but it's not always easy to spot them (especially in lengthy documents).

Always double-check your spelling (you know, dot your Is and cross your Ts) before hitting 'publish'.

There are a number of free tools like Grammarly and the Hemingway app that you can use to check for grammar and spelling errors. You can also share a draft of your article with someone to proofread before publishing.

Where to Publish Your Articles

Now that you've decided to take up technical writing, here are some good platforms where you can start putting up technical content for free. They can also help you build an appealing portfolio for future employers to check out.

Dev.to is a community of thousands of techies where both writers and readers get to meaningfully engage and share ideas and resources.

Hashnode is my go-to blogging platform with awesome perks such as custom domain mapping and an interactive community. Setting up a blog on this platform is also easy and fast.

freeCodeCamp has a very large community and audience reach and is a great place to publish your articles. However, you'll need to apply to write for their publication with some previous writing samples.

Your application could either be accepted or rejected, but don't be discouraged. You can always reapply later as you get better, and who knows? You could get accepted.

If you do write for them, they'll review and edit your articles before publishing, to make sure you publish the most polished article possible. They'll also share your articles on their social media platforms to help more people read them.

Hackernoon has over 7,000 writers and could be a great platform for you to start publishing your articles to the over 200,000 daily readers in the community.

Hacker Noon supports writers by proofreading their articles before publishing them on the platform, helping them avoid common mistakes.

Just like in every other field, there are various processes, rules, best practices, and so on in Technical Writing.

Taking a course on technical writing will help guide you through every thing you need to learn and can also give you a major confidence boost to kick start your writing journey.

Here are some technical writing courses you can check out:

Google Technical Writing Course (Free)
Udemy Technical Writing Course (Paid)
Hashnode Technical Writing Bootcamp (Free)

Technical Writing Forums and Communities

Alone we can do so little, together, we can do so much ~ Helen Keller

Being part of a community or forum along with people who share same passion as you is beneficial. You can get feedback, corrections, tips and even learn some style tips from other writers in the community.

Here are some communities and forums for you to join:

Technical Writing World
Technical Writer Forum
Write the Docs Forum

Some Amazing Technical Writers to follow

In my technical writing journey, I've come and followed some great technical writers whose writing journey, consistency, and style inspire me.

These are the writers whom I look up to and consider virtual mentors on technical writing. Sometimes, they drop technical writing tips that I find helpful and have learned a lot from.

Here are some of those writers (hyperlinked with their twitter handles):

Quincy Larson
Edidiong Asikpo
Catalin Pit
Victoria Lo
Bolaji Ayodeji
Amruta Ranade
Chris Bongers
Colby Fayock

Final words

You do not need a degree in technical writing to start putting out technical content. You can start writing on your personal blog and public GitHub repositories while building your portfolio and gaining practical experience.

Really – Just Start Writing.

Practice by creating new documents for existing programs or projects. There are a number of open source projects on GitHub that you can check out and add to their documentation.

Is there an app that you love to use, but its documentation is poorly written? Write your own and share it online for feedback. You can also quickly set up your blog on hashnode and start writing.

You learn to write by writing, and by reading and thinking about how writers have created their characters and invented their stories. If you are not a reader, don't even think about being a writer. - Jean M. Auel

Technical writers are always learning . By diving into new subject areas and receiving external feedback, a good writer never stops honing their craft.

Of course, good writers are also voracious readers. By reviewing highly-read or highly-used documents, your own writing will definitely improve.

Can't wait to see your technical articles!

Introduction to Technical Writing ‌‌

How to structure a technical article ‌‌

Understanding your audience, the why and how

‌‌ Technical Writing template

I hope this was helpful. If so, follow me on Twitter and let me know!

Hey there! You're welcome to my blog - Here I pen down articles specifically targeted at newbies in tech and front end web development and technical writing. If you're an expert, you could also use a thing or two.

If you read this far, thank the author to show them you care. Say Thanks

Learn to code for free. freeCodeCamp's open source curriculum has helped more than 40,000 people get jobs as developers. Get started

Types of Technical Documents

Instructions.

Instructions—those step-by-step explanations of how to build, operate, repair, or maintain things—are one of the most common and important types of technical writing. However, for something seemingly so easy and intuitive, instructions are some of the worst-written documents you can find. You’ve probably had many infuriating experiences with badly written instructions. Hopefully, the information on this page will help you write good ones.

Good instructions require:

Clear, concise writing
A thorough understanding of the procedure in all its technical detail
Ability to put yourself in the place of the reader, the person trying to use your instructions
Ability to visualize the procedure in great detail and to capture that awareness on paper
Willingness to test your instructions on the kind of person you wrote them for

Instructions incorporate items such as chronological organization, headings, lists, and special notices. However, you need to plan carefully before you apply these format items, in order to write effective, usable instructions.

Preparing to Write Instructions

Good instructions begin with good preparation, which involves audience, type, organizational approach, and task analysis.

Analyze your Audience

Early in the process, define the audience and situation of your instructions. Remember that defining an audience means defining its level of familiarity with the topic as well as other details, including age and ability level.

Analyze your Organizational Approach – Tasks or Tools

Instructions can be organized by tasks or tools.

A task approach deals with the things the user needs to do. For example, the process of finding free images for a technical document might involve the following tasks: research sites with creative commons licenses, review the sites and prioritize them according to size of database and ease of use, choose one site, identify key words that explain the concept you want to illustrate, etc.

A tools approach focuses on the things with which a user needs to interact. For example, the process of using a photocopy machine would involve writing steps for using each of its tools: cancel button, enlarge/reduce button, collate/staple button, etc. Instructions using this approach are hard to make work. Sometimes, the name of the button doesn’t quite match the task it is associated with; sometimes you have to use more than just the one button to accomplish the task. Still, there can be times when the tools/feature approach may be useful, depending on your audience analysis and your objective in writing the instructions.

Analyze the Procedure’s Tasks

Since most instructions are task-based, doing a task analysis is a key preliminary step in writing instructions. It’s important to determine the steps in the process or procedure you’re going to write about. Particularly in technical instructions, your understanding of the procedure could make the difference between success and failure, or at more complex levels, life and death.

A thorough task analysis involves studying how users use the product or do the task, interviewing them, and watching them. It can also mean interviewing marketing, product development, and help desk professionals. However, sometimes you may not be able to do a thorough task analysis. Typically, product developers don’t think about documentation until rather late, and it may be difficult to get marketing, development, engineering, and programming professionals to spend enough time with you to explain the product thoroughly. So you need to try the procedure yourself, if possible, and understand that you may end up doing a certain amount of educated guesswork. The developer is more likely to review your draft and let you know if your guesswork is right.

1. Identify one or many tasks

Examine the overall procedure you are describing to determine the number of instructional tasks. A task is an independent group of actions within the procedure. For example, setting the clock on a microwave oven is one task in the overall procedure of operating a microwave oven (which would include other tasks such as setting the clock, setting the power level, using the timer, cleaning and maintaining the microwave).

A simple procedure such as changing the oil in a car contains only one task; there are no independent groupings of activities. Within that task are a number of steps, such as removing the plug, draining the old oil, replacing the filter, and adding the new oil, which all contribute to the one task of changing the oil. However, you may be writing instructions for a complex procedure, which involves several independent tasks within the overall procedure. For example, if you were writing instructions for maintaining a car on your own, you’d have the following independent tasks in your instruction booklet: changing the oil, rotating the tires, checking the fluids, replacing the windshield wiper blades, and so on.

Task analysis can be complex; see a Sample Task Analysis to understand the precision and detail involved.

2. Identify the steps within each task

Once you have identified tasks, identify the steps within each task. As you can see, you “drill down” during the task analysis preliminary phase, to examine all aspects of the procedure in depth, so as not to miss anything critical to a user who actually needs to follow the instructions.

3. Group tasks logically

Finally, decide how to group tasks within a complex procedure. For example, the following are common task groupings in instructions:

unpacking and setup tasks
installing and customizing tasks
basic operating tasks
routine maintenance tasks
troubleshooting tasks

Writing Instructions

Although explaining the tasks that you identify in a task analysis provides the bulk of the content for instructions, there are more pieces to formal instructions and more considerations, such as visuals, that you need to deal with when you write. Instructions contain the following parts, often in the following order. Note that inclusion of these items, as well as their order, may vary, depending on the instructions’ content, purpose, and audience.

The title for instructions should be precise and concise. Opt for “how to” or an “-ing” phrase, such as “How to Clean your Microwave” or “Maintaining Your Apple iPhone.”

With technical instructions, the date is crucial. The date enables the reader to be certain that these instructions are the most current, and if they are not, where the instructions belong in the line of documents related to this product or procedure.

A table of contents is optional. Use one if your instructions consist of multiple tasks or have multiple sections, or if they are being presented in the form of a manual.

Introduction

Plan the introduction to your instructions carefully. Make sure it does any of the following things as appropriate, in whatever order is appropriate for your purpose and audience:

Provide a general idea of the procedure and what it accomplishes.
Indicate the scope of coverage—what the instructions will and will not cover.
Indicate what the audience needs in terms of knowledge and background to understand the instructions.
If this is a lengthy set of instructions, indicate how much time a user may need to complete the task or procedure.
Indicate the conditions when these instructions should (or should not) be used.

Preliminary Notes & Warning Notices

Although notes and warning notices should occur in the specific steps themselves, you may need to emphasize notes and warnings earlier in the instructions, especially if there is a possibility of readers ruining their equipment, wasting supplies, causing the entire procedure to fail, and/or hurting themselves. It’s fine to put important notes and warnings in two places within the instructions. Companies have been sued for lack of these special notices, for poorly written special notices, or for special notices that were out of place.

Technical Background or Theory

You may need to discuss background and/or theory in the preliminary material for certain kinds of instructions, so that the steps in the procedure make sense to your reader. This is a place to include technical definitions or descriptions if needed.

Equipment and Supplies

Notice that most instructions include a list of the things you need to gather before you start the procedure. This includes equipment, the tools you use in the procedure, and supplies (things that are consumed in the procedure such as wood, paint, or nails). Note that you may need to specify some or all of the items, with brand names, sizes, amounts, types, model numbers, and so on.

Discussion of the Steps

The following schematic shows some of the initial sections and the discussion of the steps in instructions.

When you get to the actual writing of the steps, there are several things to keep in mind:

structure and format of the steps
supplemental information that might be needed
point of view and general writing style

1. Structure and Format of the Steps

Most instructions number the tasks and steps chronologically. But there are many methods of structuring and formatting instructions, depending on your content and purpose.

Fixed-order steps must be performed in the order presented. For example, if you are changing the oil in a car, draining the oil is a step that must come before putting in the new oil. Use numbered lists for fixed-order steps. When in doubt, structure your instructions in this format. You may then use notes to indicate if there is any leeway to perform the steps in another sequence.
Variable-order steps can be performed in practically any order. Good examples are those troubleshooting guides that tell you to “check this, check that” when you are trying to fix something. Since a particular sequence is not relevant, use a bulleted list for variable-order steps.
Alternate steps offer two or more ways to accomplish the same thing, or different ways to proceed when different conditions exist. Use bulleted lists with alternate steps, with “OR” inserted between the alternatives. Or you can use a lead-in sentence that indicates that alternatives are about to be presented.
Nested steps are those in which individual steps within a procedure need to be broken down into sub-steps. In this case, number the main steps and then indent further and sequence the sub-steps as a, b, c, and so on.

2. Supplemental Information/Glosses

Often, it is not enough simply to tell readers what to do. They need additional explanatory information such as how the thing should look before and after the step, why they should care about doing this step, what mechanical principle is behind what they are doing, or even more micro-level explanation of the step. This is where supplemental information, often called a gloss, becomes important. (You know the word “glossary,” which is a set of explanations of various terms. A “gloss” is a single, brief explanation.)

The problem with supplemental information, though, is that it can hide the actual step. You want the actual step—the specific actions the reader is to take—to stand out. There are at least two techniques to avoid this problem: you can split the supplement into a separate paragraph nested under the instruction, or you can bold the instruction.

sample supplemental information/glosses in instructions

When changing engine oil, always check the owner’s manual to find the correct amount and type of oil and filter needed.

Start the vehicle and allow the engine to warm up for a minute. This allows the existing oil in the engine to warm up so that it drains out very smoothly.
Locate the oil pan drain plug and remove the plug for draining. Removing the fill cap and pulling the oil dipstick will allow good flow for the oil while draining. If there is more than one plug, drain the oil from both plugs into a container.

Illustrations are often critical to readers’ ability to visualize what they are supposed to do. Consider the example of car repair manuals which actually use photographs to illustrate procedures, or screen shots that demonstrate the process of using software. Most instructions rely on visuals. Generally, it is good to have both text and visuals in your instructions since your audience is likely comprised of people with different learning styles.

Visuals help clarify a concept that’s difficult to explain using only words. They may be used to show how something looks unassembled, how something is constructed, and how something should look once the steps have been completed. Graphics are useful since almost everyone can understand visual instructions and see exactly what they need to complete. Just be sure that the graphics you choose are appropriate and placed in close proximity to the steps they illustrate. Don’t make your audience flip pages to see the accompanying graphic.

See a sample of screen shot visuals incorporated into a simple set of instructions on How to Make a Checklist in D2L . (Desire to Learn, D2L, is a learning management system. The checklist function helps students know what tasks need to be completed within a course module.)

4. Point of View and General Writing Style

Instructions use commands, action verbs, and “you” orientation. For example, “Advance the Timer button to 4.” This approach immediately clarifies the action that the user should perform. Do not use passive voice in instructions, e.g., “The Timer button is then set to 4.” With the passive voice example, a reader may misunderstand and think that the Timer button will automatically go to 4, as opposed to understanding that they have to advance the Timer themselves.

Another of the typical problems with writing style in instructions is that writers often leave out articles (a, an, the). For example, “Press Pause button on front panel to stop display of information temporarily.” Write as you would normally write a sentence, including articles.

Don’t end the instructions with the last step. A conclusion can offer a general insight, trouble shooting information (i.e. what to do if something went wrong), and/or contact information. Include whatever is appropriate to the instructions.

Other Back Matter

You may include, as appropriate, a list of references, glossary, appendix, index, or technical specifications. Back matter items provide additional information that non-technical audiences, or audiences without specific background, may need to understand how to complete the procedure.

Final Thoughts about Instructions

As a technical or workplace writer, your ability to write good instructions carries a number of ethical implications. Keep in mind that poorly or carelessly designed instructions leave you or your company liable for damages. They also destroy your credibility and authority. Before you submit any instructions for final review, be sure you get feedback from others. For small or routine procedures, it may be enough to have a coworker review them, but more complex instructions should always be tested for usability

Instructions, adapted from Online Technical Communication, Technical Writing Essentials, and Technical Writing for Technicians; attributions below. Authored by : Susan Oaks. Provided by : Empire State College, SUNY. Project : Technical Writing. License : CC BY-NC: Attribution-NonCommercial
Instructions (pages 1-4 of 5). Authored by : David McMurrey & Cassandra Race. Provided by : Kennesaw State University. Located at : https://softchalkcloud.com/lesson/serve/Ds4qR8ZHANKM7E/html . Project : Open Technical Communication. License : CC BY: Attribution
Task Analysis. Authored by : David McMurrey & Tamara Powell. Provided by : Kennesaw State University. Located at : https://softchalkcloud.com/lesson/serve/OueEigLfnGbo8l/html . Project : Open Technical Communication. License : CC BY: Attribution
7.7 Writing Instructions. Authored by : Suzan Last. Provided by : University of Victoria. Located at : https://pressbooks.bccampus.ca/technicalwriting/chapter/writinginstructions/ . Project : Technical Writing Essentials. License : CC BY: Attribution
Writing Instructions. Authored by : Will Fleming. Provided by : LBCC. Located at : https://openoregon.pressbooks.pub/ctetechwriting/chapter/chapter-5-writing-instructions/ . Project : Technical Writing for Technicians. License : CC BY: Attribution
image of wordle with the word Instructions. Authored by : Wokandapix. Provided by : Pixabay. Located at : https://pixabay.com/photos/education-instruction-school-learn-614155/ . License : CC0: No Rights Reserved
image of person doing a task analysis. Authored by : RAEng_Publications. Provided by : Pixabay. Located at : https://pixabay.com/photos/engineer-engineering-4922775/ . License : CC0: No Rights Reserved
image of person writing at a white board. Authored by : RAEng_Publications. Provided by : Pixabay. Located at : https://pixabay.com/photos/engineer-engineering-software-4904883/ . License : CC0: No Rights Reserved
image of person with an illustration on a computer screen. Authored by : RAEng_Publications. Provided by : Pixabay. Located at : https://pixabay.com/photos/engineer-engineering-mechanical-4915799/ . License : CC0: No Rights Reserved

Chapter 8: Technical Instructions

Michael Beilfuss

Chapter Synopsis

The focus of this chapter is one of the most important of all uses of technical writing— instructions. Instructions are step-by-step explanations of how to do something: how to build, operate, repair, or maintain things. For a quick overview of writing instructions, check out this link: “Instructions: How to Write Guides for Busy, Grouchy People” ( https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/ ).

The chapter begins with a brief overview of the importance of knowing how to write instructions, followed by some basic guidelines. The chapter goes into some depth in regards to analyzing the rhetorical situation for writing instructions. The rhetorical situation includes the purpose, audience and context for any particular set of instructions. Next, we cover how to plan and organize the writing process followed by information about the content that is typically included in instructions. The chapter ends with some nitty-gritty tips on writing the instructions.

8.1 Introduction

One of the most common and important uses of technical writing is instructions—step-by-step explanations of how to do things: assemble, operate, repair, or do routine maintenance on something. Many people associate instructions with appliances, computer accessories, products that require assembly (e.g., furniture) and DIY projects. Because we do not find ourselves using them regularly or we come to expect them only in certain contexts, it is easy to forget how important they are. The quality of a well-designed instruction manual may go unnoticed. Yet, when we encounter frustration with putting together a bookshelf or toy, or with trying to figure out how to change or activate a particular appliance setting, the significance of well-written and designed instructions becomes clear.

Although it may seem intuitive and simple to write instructions, it is not always that easy. What follows in this chapter may not be a fool-proof guide to writing instructions, but it will show you what professionals consider the best techniques.

Ultimately, good instruction writing requires:

· Clear, simple writing that utilizes strong, descriptive verbs to reveal the process’s discrete actions

· A thorough understanding of the procedure in all its technical detail

· The ability to put yourself in the place of your audience and help them avoid common errors

· The ability to go through the procedure with concentrated attention and to capture that awareness on paper

· The willingness to go that extra distance and test your instructions on the audience for whom they are written

This chapter explores some of the features of instructions that can make them more complex to write, but easier for the reader to use. It also explains the common elements of instructions and how to write them.

8.2 The Rhetorical Situation

Instructions, like other types of texts, are shaped by a rhetorical situation. The choices technical writers make in regards to content and form depend on the purpose of the instructions, the intended audience, and the context in which the instructions are used. Altogether, the audience, purpose, and context of the instructions make up to the rhetorical situation. As you begin to plan your project, it is crucial to define the audience, purpose, and context for your instructions. Remember that defining your audience means defining its level of familiarity with the topic as well as other such details. (See chapter 2 for the discussion of audiences.)

Most importantly, if you are in a writing course, you will need to create a planning document that identifies the rhetorical situation and how it will inform the composition of your instructions. This will enable your instructor to assess how well your instructions are customized for the intended audience.

When writing your own instructions, consider the following ideas and questions regarding the rhetorical situation.

In general, the purpose of a set of instructions is to guide the user through a series of steps that lead to the completion of a task. However, each set of instructions will also have a more specific outcome. Identifying what that specific outcome is will help you make more effective rhetorical decisions about content and design. Ask yourself:

· What are the specific intended outcome(s) of the instructions, e.g., building a doghouse, installing an air conditioner, etc.?

· Are there other purposes that the instructions serve, e.g., offering troubleshooting advice, teaching users how to accomplish additional, simple tasks necessary for reaching the main objective, defining unfamiliar terms, etc.?

Creating a profile of your audience (i.e. the primary intended user of the document) is integral for making thoughtful choices about scope, content, and design. For some projects, it is tempting to say your audience is “everyone or anyone,” but you are better off tailoring your instructions for a specific audience. Check out this airline safety video from Air New Zealand:

https://www.youtube.com/watch?v=qOw44VFNk8Y

Ostensibly, the audience for the video is everyone and anyone (because just about anyone could be on a flight), but Air New Zealand tailor their instructions to appeal to a very specific audience (i.e. fans of The Hobbit ), while also making it accessible to anyone on the flight. Customizing their instructions so specifically allows them to really grab their audience’s attention, even if the customization is not grounded on a universal appeal.

In order to draft your instructions to serve your audience, consider these questions before writing:

Who is the primary audience? Who is the secondary audience?
What is the primary audience’s familiarity or expertise regarding the topic of the instructions?
What is the audience’s general comfort level with learning new skills related to the software, apps, craft, etc.?
What is your audience’s “typical” approach to learning? How will your instructions address the audience’s learning style, goals, and task-related needs?

Think of context as the temporal, social, technological, and cultural situation surrounding the creation and use of the instructions. The following questions will help you identify the context:

How much time will you have to complete this set of instructions?
Are there time constraints the user might encounter when reading the instructions or performing the process?
Is there a degree of urgency to the rhetorical situation that might dictate the instruction’s pace or flow? How will the design of the document contribute to the pace or flow? For example, a guide on how to properly administer CPR might need to anticipate a reader who is under duress and needs information quickly so that they can save someone’s life, whereas instructions on how to play “Mary Had a Little Lamb” on the violin will be read by a recreational audience that may not feel the same pressure or exigence.
What technological constraints must you consider in writing the instructions? Consider your skills with technology and level of access.
How will your audience gain access to the instructions? For example, your audience may access it online via a company website on a desktop computer or their smart phones. Will they need to print it?
What additional tools or materials are you assuming the audience already has? Will they have access to the technology or materials needed to follow the instructions? For example, to successfully build a bookshelf, the user will need a hammer, screwdriver, and open work area.
From what cultural perspective are you writing the instructions? Will the audience share this same cultural context? For example, a German recipe that calls for vanilla sugar, an ingredient not readily available in the United States, may need to be modified for American users.

8.3 Planning and Shaping

Once you have described the rhetorical situation, you can begin drafting your set of instructions. A comprehensive set of instructions contains many components. These are listed in the next section. This section provides a foundation for your draft.

Number of Tasks

How many tasks are there in the procedure you are writing about? The term procedure refers to the whole set of activities your instructions are intended to discuss. A task is a semi-independent group of actions within the procedure: for example making spaghetti and meatballs is a procedure that—while containing dozen of individual steps—can be broken down into three distinct tasks: 1) preparing the meatballs; 2) stewing the sauce; and 3) boiling the pasta.

A simple procedure like changing the oil in a car contains only one task; there are no semi-independent groupings of activities. A more complex procedure such as making spaghetti and meatballs, or constructing a doghouse, contains many semi-independent tasks. For example, constructing a doghouse would include the tasks of: leveling the ground, setting the foundation, building the floor, constructing the walls, adding the roof. The instructions for the Kobolt Swing Trimmer are organized by tasks – Assembly Instructions and Operating Instructions. The Assembly Instructions include further divisions related to particular parts such as the guard and the front handle.

In Figure 1, the procedure is the total sum of the actions needed to build a doghouse. The introduction and list of tools and supplies is not part of the procedure. In this schematic those sections are represented in gray.

The separate tasks that comprise the procedure are represented by the blue boxes: Level the Ground and Set the Foundation. The steps are the individual actions taken in sequential order and are nested within the tasks.

Some instructions have only a single task, but have many steps within that single task. For example, imagine a set of instructions for assembling a swing set. There could be over a 100 steps. That can be daunting. If there are no natural, semi-independent tasks, or if there are too many semi-independent tasks for clearly denoted task sections, you can simply group similar and related steps into phases, and start renumbering the steps at each new phase. A phase then is a group of similar steps within a single-task procedure. In the swing-set example, setting up the frame would be a phase; anchoring the thing in the ground would be another; assembling the box swing would be still another.

Returning to the spaghetti and meatballs example, the tasks—1) preparing the meatballs; 2) stewing the sauce; and 3) boiling the pasta—can be broken down further into phases. The task of preparing the meatballs can be divided into several phases—seasoning the meat, forming the meatballs, searing the meatballs—and each of these phases will include multiple action steps. Phases for stewing the sauce might include: dicing onions, dicing garlic, browning the vegetables in the pan, adding herbs, and simmering the sauce. But since there are a limited number of steps within these phases, and the procedure already contains natural, semi-independent tasks, there is no need to add extra phases to preparing spaghetti and meatballs.

For further discussion, see this resource on task analysis ( https://www.prismnet.com/~hcexres/textbook/task_analysis.html ).

Groupings of Tasks

Listing tasks may not be all that you need to do. There may be so many tasks that you must group them so that readers can find individual ones more easily. For example, the following are common task groupings in instructions:

Unpacking and setup tasks
Installing and customizing tasks
Basic operating tasks
Routine maintenance tasks
Troubleshooting tasks

8.4 Content

The standard sections of instructions include front matter, an introduction, the procedure (a series of numbered steps divided into tasks or phases), a conclusion, and back matter. Some sets of instructions may not use all of these sections or label them in this way. Extensive front and back matter, for example, are often found in longer, more complex manuals.

Most sets of instructions, however, contain an introduction that provides information necessary for completing the steps safely and efficiently. The introduction may include an explanation of who should carry out the task (maybe the user needs to have proficiency in a certain skill), the materials needed, any precautions that the user should take (safety tips or other warnings), and an estimate for how long the process will take, among other elements. It is often necessary to include an explanation of why the user should follow the instructions. For example, instructions for changing the oil in a car may explain why the task is necessary for the proper functioning of the vehicle.

Following this introductory material is the sequence of step-by-step instructions, divided into separate tasks. See the section below for how to draft clear and effective steps.

Lastly, instructions typically include some closing sections or appendices such as a “Troubleshooting Guide” or a section for “Tips” to help users address common problems that they may encounter while following the instructions or after completing the process.

The following is a review of these different parts you will commonly find in instructions. Most of them should be included in all instructions, but do not assume that all of them always need to be present, or that they must follow this exact order. There are other possible sections that could be included in instructions. However, all instructions should have at minimum an Opening/Introduction , a Body with numbered steps that are divided into separate tasks or phases, and a Conclusion and/or Closing sections.

As you read the following on common sections in instructions, check out the sample instructions linked at the end of this chapter. Figure 2 provides a simple schematic of the foundational elements for a set of instructions.

Introduction /Opening

Before you even get to the introduction, you need to craft a clear title that is easy to understand. You want to be detailed and specific, but also succinct. For example, some good titles would include: “How to Clean a Freshwater Aquarium,” “How to Install Long-Tube Headers on a 1999 Trans Am,” “Cleaning a Bathroom: Instructions for College Students Living on Their Own for the First Time.”

Plan the introduction to your instructions carefully. Just as the title should provide your reader with a good idea of what the instructions involve, the goal of your introduction is to give your reader general information about the process. What is it? Why should it be done? The introduction should contain an overview of the process and why it is important. Often, the writer lists the benefits of completing the process so that the reader feels good about the task they are about to complete.

The introduction/opening should do the following:

Include a title
Describe the goal and/or purpose of the instructions. Richard Johnson-Sheehan [1 [1] ] provides the following verbs as possible options:

to instruct

to illustrate

Identify the intended readers and what knowledge and background information or skills they will need to understand the instructions and complete the procedure.
Indicate the conditions when these instructions should (or should not) be used.
Give an overview of the contents of the instructions.
Provide motivation and stress the importance of the task (i.e., what does the audience stand to gain from learning this information? How will it prove useful? Why should the reader follow these instructions? What will happen if they do not?)
Indicate the time for completion for people of varying skill-levels.

The following sections should be included as part of the opening of the instructions before the tasks begin. They can be folded in as subheadings of the introduction, or they can stand on their own, depending on the rhetorical situation.

Precautionary Statements /Warnings

Instructions must alert readers to the possibility of damaging the equipment, botching the procedure, and injuring themselves or others. For these situations, use special notices (https://en.wikipedia.org/wiki/Precautionary_statement) —notice, caution, warning, and danger notifications.

The “Notice” precaution is the lowest level statement. The standard color for notices is blue. Use it to indicate when there is a risk to damage property or equipment. You can also use it to draw attention to important operational considerations. There is no threat to bodily harm or safety with a notice.
A “Caution” statement should include the safety symbol of an exclamation mark within a triangle. The standard color for caution statements and symbols is yellow. All the other higher warning should include this symbol as well, in the appropriate color code. It indicates there is a “non-immediate or potential hazard” for minor injury to a user or general public.
A “Warning” statement appears in orange and indicates that death and/or serious injury could result to users and the public. These signs are not used to indicate property or material damage, but rather the potential for personal bodily injury or death.
A “Danger” statement is the highest level precautionary statement and should appear in red. It indicates a situation with an immediate hazard that will result in death or serious injury. It is not used for property damage.

If any part of the procedure merits a precautionary statement or warning, you must include a statement at the beginning of your instructions, either as part of the Introduction/Opening or as a separate section before the tasks begin. Each of these warnings must always contain the corresponding colors and icons to help them stand out on the page. See the link above for more information. See below for more information about precautionary statements.

Technical Background or Theory

For some instructions you will need to provide a more thorough discussion of background related to the procedure. For certain instructions, this background is critical—otherwise, the steps in the procedure make no sense. For example, you may have had some experience with those software applets in which you define your own colors by nudging red, green, and blue slider bars around. To really understand what you are doing, you need to have some background on color. Similarly, you can imagine that, for certain instructions using cameras, some theory might be needed as well.

List of Parts, Tools, Materials, Equipment, and/or Supplies

Most instructions include a list of things you need to gather before you start the procedure. This includes equipment , the tools you use in the procedure (such as mixing bowls, spoons, bread pans, hammers, drills, and saws) and supplies , the things that are consumed in the procedure (such as wood, paint, oil, flour, and nails). In instructions, these are typically listed in a simple vertical list or in a two-column list. It may help to notify your reader where they can acquire the equipment or supplies. The audience needs to know and gather all the materials necessary to complete the procedure before they begin any of the tasks.

Step-by-Step Instructions

When you get to the actual writing of the steps, there are several things to keep in mind: (1) the structure and format of those steps, (2) supplementary information that might be needed, and (3) the point of view and general writing style.

Structure and Format

Normally, we imagine a set of instructions as being formatted as vertical numbered lists, and most are in fact. There are some variations, however, as well as some other considerations:

Fixed-order steps: must be performed in the order presented. For example, if you are changing the oil in a car, draining the oil is a step that must come before putting in the new oil. These are numbered lists (usually, vertical numbered lists).
Variable-order steps: steps that can be performed in practically any order. Good examples are those troubleshooting guides that tell you to check this, then check that, when you are trying to fix something. You can do these steps in practically any order. With this type, the bulleted list is the appropriate format.
Alternate steps: those in which two or more ways to accomplish the same thing are presented. Alternate steps are also used when various conditions might exist. Use bulleted lists with this type, with OR inserted between the alternatives, or the lead-in indicating that alternatives are about to be presented.
Nested steps : in some cases, individual steps within a procedure can be rather complex in their own right and need to be broken down into substeps. In this case, you indent further and sequence the substeps as a, b, c, and so on.
“Stepless” instructions: s ome instructions really cannot use numbered vertical list and that do little if any straightforward instructional-style directing of the reader. Some situations must be so generalized, or so variable, that steps cannot be stated. Generally, these are not appropriate for a classroom assignment. In your classes, you will need to demonstrate your mastery of the form with more traditional, straight-forward, sequentially numbered steps, otherwise it may begin to resemble a collection of tips or advice.

In any case, remember to divide your procedure into separate tasks or phases. It is easier for your audience to complete the procedure if they can work through it in smaller chunks.

Supplementary Discussion

Often, it is not enough simply to tell readers to do this or to do that. They need additional explanatory information such as how the thing should look before and after the step; why they should care about doing this step; what mechanical principle is behind what they are doing; even more micro-level explanation of the step—discussion of the specific actions that make up the step. When including supplementary information, it should be formatted as a “Note” or “Tip” similarly to how you would format a “Notice.” This type of supplementary information derives from “craft knowledge.” In certain circumstances, especially less formal instructions, it is even appropriate to include personal narrative to help convey your craft knowledge. [2]

The problem with supplementary discussion, however, is that it can hide the actual step. You want the actual step—the specific actions the reader is to take—to stand out. You do not want it buried in a wall of words. There are at least two techniques to avoid this problem: you can split the instruction from the supplementary information into separate paragraphs; or you can bold the instruction. In figure 3, you can see how the supplementary discussion is distinguished from the main action of the step through the use of bold-face type.

Language and Writing Style

The questions about “Audience” and “Context” earileir in this chapter can help guide you in making effective language choices. The following subsections include explanations of common linguistic features of instruction manuals along with tips for writing clearly and concisely in this genre.

Imperative Mood

Instructions, like commands, often use the imperative mood. To write in this way, address the audience directly using active voice and specific verbs. Imperative mood typically leaves out the subject (“you”) and positions the verb first.

The way you actually write the steps, sentence by sentence, may seem contradictory to what previous writing classes have taught you. However, notice how professional instructions are written—they use the imperative (command, or direct-address) and a lot of the second person. That is entirely appropriate. You want to get your reader's full attention. For that reason, instruction-style sentences sound like these: “Press the Pause button on the front panel to stop the display temporarily" and "You should be careful not to ..."

Which of the following provides the clearest instructional step?

Press the red button to begin playing the game
When the red button is pressed, the game will begin
The operator should press the button

Though a user could probably make sense of any of these sentences, the first one provides the clearest explanation of what action the user should performed because the action is the first thing mentioned. The second, passive construction does not specify who should press the button. The third example refers to a vague subject, the “operator,” which may confuse the user.

Word Choice

When writing instructions, a careful consideration of word choice is important because in some cases, the user’s safety is at risk. Always strive for clarity and concision. To make effective decisions about word choice, consider your primary audience’s level of expertise and cultural background. You may find it necessary to:

Define complex terms.
Spell out acronyms the first time they are introduced (e.g., digital single-lens reflex camera, DSLR).
Avoid using similes, metaphors, slang, jargon (unless it is defined in a glossary) or substitutions that may confuse users. Keep terminology consistent.
Use plain language. In some cases, serious legal consequences can arise when a set of instructions is unclear. For more on plain language, see the website plainlanguage.gov ( https://www.plainlanguage.gov/index.cfm ).
Include translations of the instructions into multiple languages.
Use brief and informative headings and subheadings.

Consistency and Parallelism

Parallel structure, or parallelism, means using the same grammatical structure to present information or ideas. Parallelism often improves readability and aids consistency.

This numerical list of instructions contains a step that breaks parallel structure. Which of these steps seems different from the others?

Remove the screw to open the battery compartment.
Insert batteries by following the image on the battery compartment.
Now you may close the compartment, and screw it closed.

Step three breaks the parallel structure of the list because it does not start with a directive verb.

Do the following headings use parallel structure? Why or why not?

Installing batteries
Turning device off/on
How to charge your device

Keep your word choices as accurate and consistent as possible. There is no reason to make your audience wonder if “turn,” “twist,” “screw,” and “tighten” mean the same thing. If they do mean the same thing, do not introduce the synonym simply to vary word choice. If they indicate distinct actions/movements, it may be helpful to explain that, either in a note or a glossary.

Conclusions, Closing Sections, Appendices

After all the steps are completed, you must signal the completion of the task. End the instructions with positive comments about the product and/or the process the user just completed. Congratulate the reader on a job well done. Sometimes there is a phone number for a Help Line if further assistance is needed. You might also describe the finished product or indicate other tasks the reader may now complete with the same set of skills they used to complete the procedure.

The benefits can also be restated but make sure not to use the exact words from the introduction. Readers do not like to read the same exact words/phrases/sentences in the conclusion as they did in the introduction because it feels like the writer was too lazy to actually work on the document.

Depending on the task completed in the instructions, you should include additional closing sections and/or appendices. For example, the instructions might require trouble-shooting advice, frequently asked questions, clean up and/or maintenance information, product specifications, or sources of additional information. References should be listed at the end as well.

Conclusion Examples

Conclusions for technical instruction reports are designed to provide audiences with additional facts, resources, or information that may be outside the scope of the report’s process (or topic, as indicated by the title), but are nevertheless still important to a general understanding of the subject. In many cases, technical instruction conclusions help educate the audience as to what happens after the main process has ended.

When providing instructions in the conclusion, don’t forget to rely on the verb-first sentence structure used to describe the action steps.

Conclusion Option A: Clean-Up Information

This conclusion style is appropriate for processes that create excessive waste/mess, require specific disposal instructions for hazardous substances (e.g. automotive oil; medical/chemical contaminants; nuclear materials, etc.), or require unique cleaning processes to preserve the integrity of tools, equipment, and/or the environment.

Example Topic A: How to Make Extra Crispy Chicken Wings in a BRAND X Air Fryer

Cleaning-up

Remove the Teflon-coated racks and drip tray once your air fryer has cooled (approximately 20 minutes). Wash the trays by hand with a non-abrasive towel or sponge. Alternately, clean racks and trays in the dishwasher.
Remove the door of the air fryer by opening to a 45-degree angle, then gently pulling upward; the hinge of the door should release easily. Wipe both sides of the door with a non-abrasive towel or sponge. Do not fully submerge the door in water, and do not place the door in the dishwasher! Doing so may cause water to collect in the door, which can degrade components and decrease longevity.
Use a non-abrasive towel or sponge to wipe the interior of the air fryer. For a deep clean, lightly soap the towel/sponge, wipe the interior of the air fryer, rinse towel/sponge until the soap is removed, then wipe the interior of the air fryer again.

Conclusion Option B: Maintenance or Service Information

This conclusion style is appropriate for processes involving automated machinery, electronics, or other physical components that should be inspected and/or serviced on a regular basis.

Example Topic B: How to Play Three Beginner Songs on Your New Electric Guitar

Maintaining Your Guitar’s Sound and Appearance

Guitar strings will eventually need to be replaced. A general rule is to replace strings every 3 months, or after 100 hours of playing. The material/gauge of your strings, combined with your individual playing style, will determine how quickly your strings stretch and degrade. If you notice your guitar will not stay in tune or sounds dull, these can be indicators that it is time to change your strings.
When changing strings, use this time as an opportunity to inspect your guitar for loose knobs/screws on the headstock, pickups, pick guard, output jack, bridge, backplate and neckplate. Use a damp cloth with a mild detergent to clean the front and backside of the neck, fretboard, pick guard, and tuning pegs. Oil from your hands can build up in these areas, so regular cleaning will ensure that your guitar plays consistently while also continuing to look visually appealing.
Store your guitar in an upright position so that the neck is not leaning at a sharp angle. Leaving you guitar at an angle for weeks or months can warp the neck, as can storing your guitar in an overly humid environment. Guitar cases—both soft and hard-shell—protect against humidity and collision damage. If storing in a hard case, do not horizontally stack cases on top of one another; always store guitars vertically.

Conclusion Option C: Frequently Asked Questions (FAQ)

This conclusion style is appropriate for providing audiences with additional information that will allow them to avoid common mistakes, or to answer common questions about the steps, materials, tools/equipment, or the processes’ practical applications. This style is often presented in a question/answer format.

Example Topic C: How to Start Pepper Seedlings Indoors Before Transferring to an Outdoor Garden

Q: None of my pepper seeds germinated. What did I do wrong?

A: Peppers are notorious for being somewhat difficult to germinate (but not as difficult as eggplants). If after 3 weeks none of your peppers have sprouted, start the process over, but soak your pepper seeds in water for 24 hours before planting. Additionally, some gardeners find that lightly scouring both sides of the seed with sandpaper or an emery board can improve germination rates.

Q: I don’t want my peppers to be overly hot. Is there anything I can do to limit how fiery a pepper will be?

A: Much of a pepper’s heat level (or capsaicin content) is a product of genetics, so if a pepper has been bred to be spicy there is no way to remove this characteristic in a single generation. However, watering your pepper plant regularly will help moderate capsaicin production. By contrast, if you want your peppers to be as hot as possible, you should limit watering. If your desire is to produce hot peppers, wait until your pepper plants looks a little droopy—or until the edges of the leaves just start to dry—before watering. The stress on the plant encourages capsaicin production.

Q: What is the difference between a red and a green pepper?

A: Maturity. Most green peppers will change colors as they ripen, eventually, turning red, orange, yellow or even purple. (Peppers are fruits, after all!) In addition to the color change, the flavor of a pepper also develops over time. Peppers become sweeter as they age, and a red, yellow, orange, or purple color typically indicates that sugar content is increasing and chlorophyll decreasing. This means that a mature pepper will taste less “green” or “vegetal” than an immature pepper and, in general, a mature version of the same pepper (e.g. red jalapeño) will be somewhat less spicy than the immature pepper (e.g. green jalapeño) due to the additional sugars.

Conclusion Option D: Troubleshooting Advice

Similar to the FAQ, this conclusion style can provide specific advice for avoiding both common and uncommon mistakes, or for navigating around predictable obstacles that may arise during the process. Be aware that this conclusion style does not replace traditional safety labels (i.e., notice, caution, warning, danger) but should be used in conjunction with them. Troubleshooting advice may also serve to address issues, concerns, or difficulties that might arise toward the end of a process.

Example Topic D: How to Safely Drive a Standard Transmission Automobile

Troubleshooting Driver Frustrations

If you’re experiencing difficulty mastering the clutch and keep stalling the engine, the solution may be to become more familiar with your clutch. Many cars have clutches that respond somewhat differently underfoot, requiring more or less force to depress. Learning the unique behavior of your car’s clutch will help in the mastery of this skill.

Warning: Only practice driving in safe environments, such as empty parking lots.

To gain the needed familiarity, release the emergency brake, start the car and place it in first gear. Keep the clutch depressed. Then, very slowly and without pressing the gas, release the clutch until you feel the car begin to move on its own. Keep the clutch in this mid-way position for a few seconds and make a mental note of how much you released the clutch to get here. Then fully engage the clutch to slow your momentum. Repeat this until you consistently find the spot in the clutch where the car begins to roll on its own. From this position, slowly depress the gas pedal with your right foot while simultaneously—but slowly—releasing the clutch the rest of the way.

If after stalling you quickly try to restart the car but turning the ignition does not cause the engine to fire, one of two things may be happening:
You may own a model car that requires the clutch to be fully depressed/engaged when starting the car;
You may own a model car that requires you to place the ignition in the full OFF position (i.e. cutting all power to the car but not removing the key) before a restart is allowed.
Driving in mud or snow can prove tricky in any automobile, but some drivers notice that standard transmission cars are more likely to “peel out” in mud or snow. If you’re experiencing difficulty getting traction in mud or snow when pulling away from a parked location, place the car in second gear. While drivers are generally instructed to begin accelerating from first gear, in some weather conditions starting from second gear may be offer potential for more control.

Conclusion Option E: Sources of Additional Information

This conclusion style provides the audience with additional resources (books, articles, websites, databases, etc.) should they want to satisfy their curiosity and learn more about the process itself.

Example Topic E: How to Pick the Right Winter Resort for Your Family Vacation

Sources of Additional Information

The following channels and websites offer in-depth analytics and reviews of ski/snowboard resorts:

JB Boudhens ( https://www.youtube.com/channel/UCY&D*D )

This video channel offers reviews of winter resorts using 10 different criteria. Boudhens is an amateur snowboarder who provides casual, unscientific but earnest reviews of resorts with copious Go-Pro footage of Boudhens and friends performing tricks. Boudhens’s channel is unique in that he is more interested in assessing new school terrain parks and stunt features than evaluating backcountry and/or off-piste options.

Powderhounds ( https://www.powderhounds.com/ )

The definitive online site for winter resort reviews, Powderhounds uses an eight-criteria scale to assess the overall character of each winter resort. Powderhounds provides reviews of resorts both in the United States and beyond, and is also a reliable site for determining how family-friendly a resort might be. Also offers helpful breakdowns of terrain difficulty percentages.

OpenSnow ( https://opensnow.com/ )

Because not all winter resorts receive equal snow amounts or storm frequency, ensuring that the resort you’re planning on patronizing will in fact have the conditions you are expecting is essential research. OpenSnow provides global resort snowfall totals, base depth, current conditions, as well as storm predictions. Its network of local skier/meteorologists provide reliable daily weather forecasts by incorporating multi-sourced models and imaging tools. Snow estimates are to be trusted as expected minimums, as Open Snow’s conservative predictions regularly underestimate snowfall totals.

Conclusion Option F: Product Specifications

When a process focuses on assembling new equipment or machinery, this conclusion style provides technical information such as the final weight of the assembled product, the dimensions of the assembled product, materials and components of note, energy usage data, warranty information, and any special instructions for transportation/care of the product.

Example Topic F: How to Assemble the Trash-Compactor 1000X

Product Specifications

Finished dimensions: 10’ x 6.25’ x 8.5’ (length x width x depth)
Finished weight: 2,389 pounds
Maximum Capacity: 350 pounds/load
Estimated electricity usage/load: 0.3 kWh

Conclusion Option G: Tips and Tricks

The conclusion style provides audiences with general advice that may improve their ability to perform the described process or develop a related skill. This option can also be used to combine elements of other conclusion styles (for example, providing clean-up instructions, maintenance routines, and troubleshooting advice in the same conclusion), or to address variations on the process that might allow the audience to make adjustments and changes (e.g. adding optional ingredients to a recipe; altering fermentation temperatures used by breweries and distilleries to achieve different ester profiles).

Example Topic G: How to Forage Edible Chanterelle Mushrooms

Tips and Tricks

Finding chanterelle mushrooms can be difficult enough, but cleaning them is another story. The advice below will help make the process efficient while also ensuring that the quality, taste, and integrity of your mushrooms is not compromised. Handle your mushrooms gently; they are both rare and fragile, and should be treated as such.

Do not wash or clean mushrooms until you are ready to consume them.
Store unwashed mushrooms in a paper bag in the refrigerator.
Do not fully submerge chanterelle mushrooms in water when washing them. Most mushrooms absorb water readily, which can affect the way they cook and their final taste/texture.
Use a toothbrush or medium-stiff bristled paint brush to dust away any dirt that has accumulated in the chanterelle’s false gills, on the cap, and along the stem.
Wipe mushrooms down with a damp paper towel to remove grit.
Wet a second toothbrush/paintbrush in a bowl of water and clean the false gills a second time.
Wipe a second time with a damp paper towel, then place on a dry towel until ready to cook.

8.5 Graphics

Probably more so than in any other form of writing (except maybe comic books), graphics are crucial to instructions. Sometimes, words simply cannot clearly explain the step without the assistance of images. Illustrations are critical to readers' ability to visualize what they are supposed to do. Your reader will need graphics to refer to and act as a guide through the process. Remember to label the graphics as Figure 1, Figure 2, and so on, and then title each graphic so readers know what they are looking at. Graphics can never fully replace text, and they MUST be referred to within the step-by-step part of the instructions, e.g., “Tighten the bolt located to the left of the main shutoff valve (see Fig. 5) by turning the socket wrench clockwise.”

In a technical writing course, instructions usually require you to include illustrations or other kinds of graphics—whatever would normally be used in the instructions. The problem of course may be that you do not have access to graphics that would be suitable for your particular instructions, and that you do not feel wildly confident in your artistic abilities. There are ways to overcome these problems! Take a look at these suggestions about graphics ( https://www.prismnet.com/~hcexres/textbook/graphics.html ). You will see not only suggestions for creating graphics, but also requirements on their format. (See chapter 5 for more information on graphics and design.)

Given the ubiquity of smart phones, and the increasing quality of the cameras they include, it should be no problem to produce high quality graphics for your instructions for a class project. If you are creating instructions as part of your job, you may need to hire a professional photographer or illustrator, and/or rely on drawings by engineers. In any case, it is crucial that you do not simply copy and paste images from internet search. (See chapters 4 and 10 for the ethical practices regarding the use of graphics.)

Document design refers to the way information is organized and presented. Because visual elements require less time to process, users will typically notice—and respond to—quality of design before quality of content. Minimally, design includes making choices about layout, order of information, font size, typeface, headings, color, and white space. Design elements should guide the user through the instructions smoothly. This means making the document scannable; a scannable document allows users to navigate through the content to locate specific information. As with any document, decisions regarding design should consider the audience, purpose, and overall ease of use. (See chapter 5 for more information on document design.)

Consistency/Repetition

Using design elements in a uniform way throughout the entire document guides users by giving them a sense of what to expect (e.g., the same typeface and size for all headings; the same layout from page to page).

Use design elements to highlight specific information or features of the instructions (e.g., capitalizing a word for emphasis; placing a box or border around an item; changing colors for emphasis). Contrast is primarily effective when a document uses consistency overall. If there is a lack of consistency, it is more difficult to create contrast.

Organizing items on a page with horizontal and/or vertical alignment creates hierarchy and structure, and can help achieve balance, contrast, or consistency.

Distribute items evenly across a given space. To achieve this, each item’s weight--that is, the tendency of the eye to gravitate toward an item--should be considered. For example, since an image weighs more than text, decisions about image placement should consider how to balance its weight against other items in order to prevent visual confusion.

White Space

Use white space to create a professional, balanced document. Rather than indicating the color of the space, this design element refers to an absence of images and text. White space helps distinguish between individual items and groups of items (i.e., sections of the manual) and makes scanning documents easier.

Grouping/Proximity

Place related images or content close to one another. For example, grouping together images of all the materials needed to complete the given task.

Select colors to create contrast and emphasis, to guide readers across space, and to design a visually pleasing document. You should consider the document overall in order to create a consistent color scheme. For example, if you want to use blue in your document, you will want to ensure that it is used consistently and complements other document colors. This is particularly important when integrating color graphics and/or images.

In your instructions, make good use of headings. Normally, you want headings for any background section you might have, the equipment and supplies section, a general heading for the actual instructions section, and subheadings for the individual tasks or phases within that section. Take a look at the examples at the beginning of this chapter. See headings ( https://www.prismnet.com/~hcexres/textbook/headings.html ) for common requirements.

Similarly, instructions typically make heavy use of lists, particularly numbered vertical lists for the actual step-by-step explanations. Simple vertical lists or two-column lists are usually good for the equipment and supplies section. In-sentence lists are good whenever you give an overview of things to come. See lists ( https://www.prismnet.com/~hcexres/textbook/lists.html ) for common requirements.

Number, Abbreviations, and Symbols

Instructions also use plenty of numbers, abbreviations, and symbols. Follow the link for guidelines ( https://www.prismnet.com/~hcexres/textbook/gram2.html#numbers ) on these areas.

Precautionary Statements/Warnings

You must alert readers to possibilities in which they may damage their equipment, waste supplies, cause the procedure to fail, injure themselves or others—even seriously or fatally. Companies have been sued for missing, poorly written, and out-of-place warnings. Figure 4 provides an example of a clear precautionary statement.

All procedures that require warnings must also have precautionary statements at the beginning as part of the introductory material. Warnings must also be dispersed throughout the procedure. It is especially important to include warnings before a step where damage or injury could occur. Do not create instructions where the user has already completed the process and injured themselves before the warning comes. If someone is injured as the result of misplaced, hidden, or omitted warnings, the technical writer can be held accountable. Notices, on the other hand, including user information and tips, are typically placed after a step (see figure 5 below).

Also, remember legal and ethical obligations. It is the writer’s job to protect the reader from harm or damage. That being said, any set of instructions needs a careful balance of warnings strategically placed throughout the document. If the writer overuses them, there is a risk of scaring the user. Alternatively, a reader may become numb to the warnings if there are too many of them, and may start ignoring the warnings.

If the writer under-uses warnings, there is a risk of someone getting injured. Strike a balance.

There are standard precautionary statements that are color-coded and used for danger, warnings, cautions, and notes or notices (see above, or you may review them here: Precautionary Statements ) (https://en.wikipedia.org/wiki/Precautionary_statement) . You will be expected to incorporate information from this link into the instructions you create for the course.

8.7 Revision Checklist

As you reread and revise your instructions, watch out for problems such as the following:

Make sure you provide real instructions—explanations of how to build, operate, or repair something.
Write a good introduction—in it, indicate the exact procedure to be explained, indicate audience requirements, and provide an overview of contents.
Make sure that you use the various types of lists wherever appropriate . In particular, use numbered vertical lists for sequential steps.
Use headings to mark off all the main sections and subheadings for subsections. Remember that no heading "Introduction" is needed between the title and the first paragraph.
Use precautionary statements as appropriate.
Use graphics to illustrate any key actions or objects.
Provide additional supplementary explanation of the steps as necessary.
Remember to create a section listing equipment and supplies, if necessary.

8.8 Student Samples

Below are links to a number of sample sets of instructions written by students at Oklahoma State University.

Breadboard and Soldering Basics: Making an Electron Harmonix LBT - 1 byAustin Johnson
Driving Motor with an Ultrasonic Sensor: An Arduino Project by Emilie Jenkins
How to Create a PID DC Motor Position Controller by Diego Colon Serrano
How to Record Vocals in Ableton Live 9 by Daniel Rodriguez.
How to Solve a Rubik's Cube by Nick Burt

8.9 Activity – Sample Technical Instructions Analysis

Find a set of sample instructions. Look in your junk draw, under the refrigerator, or wherever those instructions end up after you have finished setting up the product. As a last resort you can look online.

The sample you find should be a set of instructions, not specifications or a procedure. The main difference between instructions and specifications is that specifications are written for experts in a particular field. Instructions are typically for novices. User manuals are a separate category that often contain instructions within them. If you find a manual for this assignment, be sure to concentrate on the instructions part.

Use the questions below to analyze the sample instructions you find. Note that professional instructions do not always use the same headings as those below. For example, they almost never use a heading of “Introduction,” but rather include introductory information under other headings.

Introductory Sections

Analyze the content of the introductory sections. Identify and explain each of the elements of the introduction (see above). Are there any left out? Why? Is there anything in the introduction that does not seem to be covered by the elements described above? What is their purpose? Are there any other features that are especially noteworthy? Who is the audience for these instructions? Include analysis of any precautionary statements here.

Body Sections

Analyze the body sections. Identify and explain how the instructions meet (or fail to meet) the requirements for the body section identified in this book. Do the instructions contain anything not mentioned in this chapter? What and why? Are there any other features that are especially noteworthy?

Conclusion Sections

Analyze the conclusion sections. How do the sample instructions measure up to what is described above? What types of information is contained in the conclusion? Is there anything not mentioned here? Any other noteworthy features?

Graphics and Design

Analyze the design and graphics. (See chapter 5 .) Briefly explain how the instructions measure up to what you learned in the design chapter. How do they adhere, or how do they miss the mark? Explain. Do they use a variety of graphics? Are there enough? Too many? Anything else noteworthy about graphics or design?

[1] Johnson-Sheehan, Richard. Technical Communication Strategies for Today . Second Edition. Pearson, 2015.

[2] See Van Ittersum, Derek. “Craft and Narrative in DIY Instructions.” Technical Communication Quarterly , vol. 23, 2014, pp.227-246.

Attribution

Material in this chapter was adapted from the works listed below. The material was edited for tone, content, and localization.

Strategies for Peer Reviewing and Team Writing , by David McMurrey, licensed CC-BY .

Creating Rhetorically Effective Instruction Manuals, Writing Commons , by Madelyn Tucker Pawlowski and Antonnet Johnson, licensed CC-BY-NC-SA .

ENGL 145 Technical and Report Writing , by the Bay College Online Learning Department , licensed CC-BY .

Johnson-Sheehan, Richard. Technical Communication Strategies for Today. Second Edition. Pearson, 2015. ↵

Chapter 8: Technical Instructions Copyright © 2019 by Michael Beilfuss is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License , except where otherwise noted.

Share This Book

20 Technical Writing Examples (Word & PDF)

How often have you picked up an instruction manual of some sort and found that you really could not understand the message or follow the instructions after reading it? The document did not make sense and did not help you at all. This is an example of technical writing that did not achieve the objective of turning a complex subject into something the average person understands.

We all have had this experience at one time or another. A good technical writer can take a complex subject or set of instructions and turn it into everyday language that we all understand. Technical writing has been around for centuries; however, recently, it is becoming recognized as a highly valuable skill for anyone writing instructions for consumers, in technology-related businesses, and many others. Many people are finding full-time work that is rewarding and pays well;

What is Technical Writing?

Technical writing has become a critical skill set that many companies recognize they require for their products to achieve success in the marketplace. Translating engineering and scientific jargon into readable information that is easily understood by operations personnel and the average person is both challenging and interesting work. It is also highly valued.

Technical writers must be able to understand the technology or complex instructions. They may need to learn about new technologies and processes before turning that information into easily understood instructions. This leads to lifelong learning situations for many writers.

They also have to understand their audience and write accordingly for that audience. Operations people in a technology company have a better understanding of technology than the average person. The style of writing and the information discussed must be written for these two distinct audiences.

A broad definition defined by the Society of Technical Communication as “any form of communication that shows one or more of the following qualities:

Communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations.
Communicating by using technology, such as web pages, help files, or social media sites.
Providing instructions about how to do something, regardless of how technical the task is or even if technology is used to create or distribute that communication.”

Technical writing is becoming more common as our society embraces technology more and more. This style of writing must also be professional, grammatically correct without spelling mistakes, and avoid jargon or acronyms as much as possible.

Technical Writing Examples & Templates

How Technical Writing Examples Can Help You?

As a technical writer, one of your main tasks is to understand the product, learn how to use it, and interpret the instructions provided to you by the developer, manufacturer, or creator. Working on a variety of projects provides a lifelong learning opportunity for many writers who enjoy this type of work. It can be very rewarding.

Anytime a consumer purchases a product of some kind, some instructions come with it, covering installation procedures and user manuals to help you know how to use the product and gain the most out of it. These are technical documents written by a technical writer. They cover everything from thick car manuals to one-page instructions on how to connect your coffee maker. Consumers find these documents very helpful every day they purchase a product.

Technical writing is a growing industry due to increases in scientific areas and technical products. However, technical writing is not limited to technology. Writers are needed in academia, broadcasting, government, energy, transportation, financial services, telecommunications, safety, and health, security, and more areas are becoming available every month.

The Purpose of Technical Writing

The purpose of technical writing is to take complex information written in technical or industry jargon and turn that into concise, clear information that can be understood and utilized by the reader. The document might explain how something works, how to assemble something, how to use something, or how to maintain an item.

The information should be easy to comprehend by individuals not familiar with the product and perhaps folks who have no understanding of how to use a particular product, e.g., a computer. There are different styles of technical writing – informative, detailed instructions, etc. consumers may use the information for many different purposes, including making decisions about financial products, for example.

Essential Characteristics of Technical Writing

While there are different types of technical writing, the main objective is to take complex information and translate it into an informative narrative that explains the topic to a variety of people in the terminology they understand.

Some of the characteristics of technical writing include:

Clear and Concise
Solid Structure
Detailed and Informative

Direct – avoid jargon, acronyms and avoid flowery or eloquent writing styles. If you must use acronyms, always spell them out in long form the first time you use the acronym in each section of the document. Include an acronym list somewhere in the document.

Clear and Concise – stay focused on the subject matter, use short sentences that convey clear instructions or details.

Solid Structure – your document should easily flow naturally from one topic to the next. As the reader reads the document, information should be presented in a logical manner that makes sense to the reader. Use proper grammar and check for spelling mistakes.

Detailed and Informative – do not leave out details or make assumptions about the reader’s understanding of the topic. Provide all of the details someone who has no knowledge of the subject will need to understand the topic.

When to Use Technical Writing?

Technical writing is used in many different fields and situations. It is also essential that the correct type of technical document be used to have the desired outcome. As a writer, you may have to make the decision, or your client may indicate what type of document and when they want to use it. The following area few examples of when technically written documents are used:

Technical reports
Technical manuals
Technical proposals
Specifications
Guides and handbooks
Installation guides
Operating procedures

Technical reports – to provide analysis, conclusions, recommendations with sufficient information for the reader to draw conclusions and make decisions.

Technical manuals – to provide instructions on how to use a program, a device, or a product

Emails – used to share company-wide instructions or communications

Technical proposals – describe a project, including planning activities, methods and procedures, anticipated results and benefits, and may also include a budget.

Specifications – provide details concerning the structure, materials, design, packaging with sufficient detail that an external company could reconstruct it or produce it for a client.

Guides and handbooks – for users to follow to assemble or use a product

Installation guides – provide instructions for end-users to install a product in their home, office, or manufacturing plant

Operating procedures – provides step by step instructions to complete routine operations to maintain consistency and quality

Warranty – provides warranty description information for the product, labor, shipping, etc.

How to Become a Technical Writer?

While there are no current degrees offered for technical writers, practical writing skills, experience, and building a portfolio of written documents are helpful to win assignments and impress employers.

The most difficult step is to find your first assignment. Practice writing and post these as examples. Use tools to assist with grammar and spelling. Check for plagiarism and assign credit when specific information must be used and quoted. Build your portfolio one document at a time. You may have an interesting area that you are knowledgeable in. Focus on niches that build on your industry knowledge and contacts.

Many technical writers prefer freelance writing to work in-house. There are advantages to both, including hours, work, salary, and security, depending on your mindset and approach to your career. There are a variety of online systems that cater to freelancers.

Consider taking online courses in subject fields that you may be writing about. Read all the time to improve vocabulary and become a subject matter expert in the field you chose for technical writing.

Join professional organizations to network with other writers and contacts who may know about writing projects and opportunities. There are many opportunities available for those people who can write and are continually improving themselves.

Many companies place a great deal of value on employees who are skilled in both the technical field they work in as well as have the ability to write and communicate their fields clearly and concisely.

Technical Writing Processes

Many technical writers will develop their process to follow to help them deliver high-quality, clearly written documents for their clients. However, some of the steps that most successful writers include are:

Preparation
Who is the Audience
Who is the User
Maximize the User Experience
Layout the Document Plan
Check with the Experts
Prepare the Document
Write Accurately with an Active Voice
Avoid Jargon
Visual Check
Add Graphics
Technical Review
User Review

Preparation – gather information such as the document type, subject, goals, scope, and audience. Gather as much raw material as you can to use as input for the document.

Who is the Audience – define who the end customer is and how they will use the information. You may have to remind your client or at least agree on the answer before starting.

Who is the end-user – is the user new to the topic, or do they have expertise in the subject. They may have their expectations of what should be in the document. What are their concerns, and how much knowledge do they have of the subject?

Maximize the User Experience – consider how the user will use the document and write accordingly. Writing for the end-user can be quite different than writing for the client who has intimate knowledge of the subject.

Layout the Document Plan – map out the document subject areas and flow in a logical manner that flows and contributes to the end goal for your document.

Check with the Experts – use the experts and technical documents as references during the writing process. It is impossible to fully understand everything about a given product or process.

Prepare the Document – begin writing the document while keeping the following points in mind. Write accurately with an active voice, avoid jargon, is the document visually appealing, do a visual check, and add graphics to assist in illustrating concepts and processes.

Review – the document for spelling, grammar, sentence structure, paragraph structure, and does it meet both your client’s aims and objectives as well as the end-user?

Technical Reviews – are always a good idea. Utilize your experts to review the technical aspects of the document.

User Review – if possible, arrange for users to review the document and identify any questions, concerns, or confusion they may have as they work through the document.

There are many frequently asked questions regarding technical writing. We have included a few of the more common questions in the following section.

What are the types of technical writing?

Each type of technical writing has a purpose and a particular type of audience. Regardless of the type, it should be direct, concise, clear, clear writing structure, informative, and detailed. The following list of different types of technical reports are some of the most common types in use:

Is a Manual an Example of Technical Writing?

Manuals are examples of technical writing. Manuals are written for almost every product delivered to consumers as well as to commercial customers. Manuals describe how to assemble a product, how to install a product, how to operate a product, and how to maintain a product. These could be separate technical documents or assembled all in one document.

Technical writers must also consider the audience for the manual. If the manual is for the general consumer without a high degree of technical knowledge, it must be written with simple, clear, step-by-step instructions. On the other hand, if the product is aimed at a highly technical audience, the manual must still provide clear, concise instructions but can include a much higher level of technical information for the reader.

What are the technical writing skills?

Technical writing skills must include the basic writing skills of grammar, spelling, sentence structure, and document structure organization. Many people use various online tools to help them with booth grammar and spelling accuracy.

In addition, writers must be able to take technical information, interpret and understand it and translate this information before writing it down using language the intended readers can use to help them utilize the product. You must be able to take high-level information, process it, and write it in a document that is easily understood.

Writing in a direct manner that is straightforward and clear with a clear structure that is informative and sufficiently detailed for the end-user is the objective of every technical writer.

How is technical writing unique?

Technical writing is unique from many other types of writing. It can be best described by describing what it is. i.e., if it includes one or more of the following elements, it is considered technical writing:

Communication about technical , specialized processes, applications, or regulations
Communication using technology – e.g., social media, help files or web pages
Communicating instructions – how to do something, whether it is technical or process-oriented

Writing that does not fall within these three points is probably not technical writing, although many of the same skills are required, e.g., excellent grammar and spelling are considered the basics.

Technical writing is a burgeoning industry that continues to grow in our technology-driven society. Technical writing skills are in demand within companies as well as for freelancers interested in jobs in many industries. Many technical writers focus on a specific area of technology to help improve their understanding and ability to translate technical information into clear, concise, and easily readable information for non-technical readers. Technical writers have opportunities to learn about new technologies and deliver value to their customers, driving increased sales and customer satisfaction. If you cannot understand how to use the technology, customers will not purchase it or recommend it. Technical writers can get their start by practicing writing documents and posting them online to show their work. They can bid on jobs using online freelance systems to build up a clientele and customer base. They should use available online tools to check grammar and spelling to ensure their work is high quality. They must also consider the end customer of their writing products. For one set of clients they may need written step-by-step instructions that are acronym-free. While for others with a high level of technical skills, they can prepare documents at a higher level of technical communications. All technical documents should be written in a direct manner that is straightforward and clear with a clear structure that is informative and sufficiently detailed for the end-user.

How did our templates helped you today?

Opps what went wrong, related posts.

Free Gradebook Templates

Teacher Evaluation Forms and Templates

Vertical Timeline Templates

16 Printable Homework Planners (100% Free)

Classroom Management Plan – 20 Templates & Examples

Op-Ed: What Is It and How to Write it?

20 Editable Homeschool Schedule Templates

20 Balancing Chemical Equations Worksheets

Thank you for your feedback.

Search Utah State University:

Technical writing standards, style and format.

When writing technical documents, engineers rely on style manuals, which provide standards for writing and designing documents. Style manuals ensure consistency in writing and formatting documents written for academic or workplace communications.

Academic disciplines, including academic journals, have their own style manuals. These style manuals are used in the production of theses, dissertations, or journal articles.

Organizations use company-specific style manuals that contain guidelines for producing technical documents, business correspondence, professional presentations, and visual features (trademarks and logos). Document format and punctuation rules are commonly found in these style manuals. Company-specific style manuals often contain templates, which are used when creating written technical documents (progress or status reports, design reports, proposals, etc.), correspondence (letters, memos, and emails), or presentation slides.

General Format Guidelines

The following guidelines represent generally accepted technical writing guidelines. As a reminder, guidelines may change based on the discipline, professor, employer, or journal the document is written for.

Technical documents typically contain:

Single spacing
Left justification; full justification is preferred for theses, dissertations, and journal articles.
One blank line between paragraphs OR indented paragraphs with no blank line between
Serif font (Times New Roman), 12 pt. font size. When documents are written for electronic media, however, a Sans Serif font (Calibri or Arial) is typically used.
One-inch margins. Margins may need to be adjusted when using company letterhead or when binding formal reports.

Stylistic Elements

Writers of technical information take into account the audience’s level of knowledge regarding the topic and the purpose of the document. In other words, “Why does the reader need this information and what will they do with it?” The following guidelines help writers achieve a readable style.

Acronyms and Abbreviations

Abbreviations are shortened forms of words such as ASME for American Society of Mechanical Engineers. Acronyms are formed when the abbreviation forms a pronounceable word such as NATO for North Atlantic Treaty Organization.

Abbreviations and acronyms should be spelled out the first time they appear in a technical document with the shortened form appearing in parentheses immediately after the term. The abbreviation or acronym can then be used throughout the paper.

Example: The Society for Technical Communication (STC) is a professional association dedicated to the advancement of technical communication, content, and information management.

Common abbreviations (U.S.) or acronyms (NASA) do not need to be spelled out when first used in a document.

Ambiguity occurs when words or passages can be interpreted in more than one way. Abstract language, misplaced modifiers, and vague pronoun reference can cause ambiguity. To make writing clear, avoid:

abstract language ( really, quite, severely, very )
overusing pronouns, particularly it, these, and this
imprecise or subjective terms ( fast, slow, tall, small )
words that have no precise meaning ( bit )

Analogies and Metaphors

Analogies and metaphors in useful in technical writing to illustrate abstract or complicated ideas by making comparisons between two generally unlike things.

“When two atoms approach each other at great speeds, they go through one another, while at moderate speeds, they bound off each other like two billiard balls.” Sir William Bragg

Writing with the intended audience(s) in mind is one of the most fundamental concepts of technical writing. Many technical documents will not only be read by the first person (primary audience) but may also be read by secondary audiences: readers in various levels of management, prospective financiers, or even individuals who access information without the writer’s knowledge.

For this reason, it is important to consider who may read your documents beyond the primary audience and write with any additional audiences in mind. This means targeting information appropriate for the knowledge of the audience(s) and using accessible language that both technical and non-technical audiences can understand.

Cliches, or figures of speech, are terms that have no concrete meaning and can affect the tone and professionalism of a document. Cliches should be avoided in technical writing. Examples include:

water under the bridge
writing on the wall
easier said than done
close the deal

Conciseness

Concise documents convey meaning using the fewest words possible without sacrificing meaning or clarity. To achieve conciseness:

Eliminate empty/wordy phrases ( there is/are and it is ). These are considered to be indirect phrases and tend to be unclear and wordy. Direct statements, on the other hand, are clear and concise. Instead of: “There are 25 students who have already expressed interest in next year’s program.” Use: “Twenty-five students have already expressed interest in next year’s program.”
Write using the active voice Instead of: “It was determined that the machine was broken by John.” (10 words) Use: “John broke the machine.” (4 words)
Avoid using weak verbs Instead of: My recommendation is for a larger budget. Use: I recommend a larger budget.
Eliminate filler words (very, quite, really, somewhat, that)

Contractions

Contractions are shortened forms of words with the missing letters represented by an apostrophe such as “you’ll” for “you will” or “didn’t” for “did not.” Contractions are unprofessional and informal and should be avoided in most technical documents.

Generalized Statements

Generalizations are broad statements or ideas that are applied to a group of people or things and should be avoided in technical writing. These statements are difficult to substantiate and are too broad to be supported.

The only way to learn another language is to visit the country where it is spoken.

Cats are nicer than dogs.

Gender-Neutral Terms

Avoid specifying gender when possible. Gender specific language can create stereotypes, make generalizations, and exclude gender. Individuals should not be referred to solely as he or she . To achieve gender neutrality:

Use generic terms when referring to specific groups of people (“supervisors”)
Avoid gender-specific pronouns (“his” or “her”)
Use gender-neutral titles when referring to people “(sales representatives” not “salesmen”
A student should always do his homework. (not gender neutral)
A student should always do his or her homework. (gender neutral)
Students should always do their homework. (gender neutral)
A student should always do their homework. (gender neutral) *

*While it may seem strange or incorrect to use the plural their to refer to a single student, their has become the preferred replacement in many places in order to ensure gender neutral language. It is no longer considered grammatically incorrect to use their as a singular pronoun in this context.

In technical reports, headings are used to organize documents, guide the reader, and break content into manageable chunks of information. Readers often peruse headings and read those sections that pertain to them.

Headings organize content into large sections (major headings) and then into smaller sections (sub-headings). Headings are formatted by level (first level, second level, third level, etc.) and vary in their position and formatting. Discipline- and employer-specific style manuals will provide guidelines in the placement and visual layout of headings. Headings vary in the type of information they provide:

Brief topic headings use short words or phrases Example: College Applications
Statement headings use sentences or phrases and are more informational in nature. Example: College Application Process
Question headings are useful when writing documents that explain how to do something. Example: How do I Apply for College?

When using headings:

Construct headings in a parallel fashion
Try to avoid starting headings with a, an, or the
Aim for at least two headings at each level; avoid dividing a section into a single sub-section if possible
Avoid repeating the wording of a higher-level heading in a sub-heading
Use headings to create the table of contents (if applicable to the document)

Jargon is often called professional slang and consists of terms specific to a particular organization. Examples of jargon include terms like “flame” or “FUBAR.” Jargon sets members of an organization apart from non-members. When communicating with individuals who are likely to be unfamiliar with jargon, avoid using the term.

Lists are useful in technical writing for three purposes: to write a series of related items, to describe a series of tasks, and to make items visually accessible. Lists can be written in a sentence (as in the previous sentence) or set off from the text vertically. Items listed vertically are prefaced with a bullet, number, or checkmark. Bulleted lists make items easy to see or locate, numbered lists organize steps in a process, and checklists communicate items that need are required or need to be completed.

Lists are prefaced with a lead-in phrase ( Items to review for the training: ) or sentence ( The following topics will be reviewed at the training: )

Key points to keep in mind when creating lists:

Lists should be constructed in a parallel fashion.
Lists comprised of brief items typically contain no ending punctuation.
Lists with no sequence required should be arranged logically (most to least important, alphabetical)
Lists written as full sentences should use appropriate ending punctuation.

Narration (Point of View)

When writing, it is important to use appropriate tense and narration. Engineers often write to explain how something happened: a lab procedure, a site visit, an accident, a recommendation.

Third person narration is most often the appropriate choice in technical documents and academic journals, but in some cases it might be appropriate to use first or second person (common in business correspondence).

Examples: First person narration , “I” words are used. I should get good grades in college. We should get good grades in college. Second person narration , “You” words are used. You should get good grades in college. Third person narration , “he/she/neutral” words are used. A student should get good grades in college.

Students should get good grades in college.

Objectivity

Technical documents present facts, data, evidence, calculations, results, and theories, which must be presented in an impersonal, neutral, and objective manner. Avoid use of the word “feelings” or the verb “feel” in technical writing.

Phrases such as “I feel this is the best approach” evokes emotion, is not objective, and can lend uncertainty to technical writing. Similarly, “When the weight feels right” should not be used in describing inanimate objects.

Paragraphs are the building blocks of documents. It is important to keep in mind the basic elements of paragraph construction: each paragraph should contain a topic sentence that is well-developed and supported, discuss one idea, and transition to the next paragraph.

In technical writing, paragraphs are generally kept to 4-6 lines. Short paragraphs emphasize main ideas, encourage conciseness, keep the reader’s attention, and break up content into manageable chunks.

Parallelism

Parallelism means using the same structure for listed items. These items can occur in a sentence, in a table, in a bulleted or numbered list, or in headings. Sentences with parallel structure are easier to read and flow more smoothly.

When creating a bullet list, all items in the list should be parallel in construction.

Redundancy means using two or more words that essentially mean the same thing. Redundancy affects conciseness.

a new innovation
absolutely true
red in color
cylindrical in shape

SI versus Customary Units

Systeme Internationale (SI) units are the most widely and officially recognized system of metric units for weights, dimensions, and other physical measures in technical writing. Technical documents should use SI units in text, figures, tables, and equations.

Sentence Length

In technical writing, uncomplicated sentences are used to state complex ideas. Long, complex sentences tend to confuse readers. Strive for a sentence length of 10-20 words. A document should not be constructed, however, of short, choppy sentences. Varying sentence length can encourage readability, make comparisons, and contrast information.

Technical Terms and Definitions

When introducing a technical term in a document, italicize and provide a brief explanation of the term the first time it is used. There are generally three types of technical definitions: informal, formal, and expanded.

Informal definitions contain a word or brief phrase, often in parentheses, that gives minimal information about the term.

“At the southwest corner of the mall site, we found 16 barrels of creosote (a coal tar derivative) buried under three feet of sand.”

Formal definitions are typically a full sentence that distinguishes the term from other similar terms and includes the term itself, a class to which the term belongs, and distinguishing feature(s) of the term, which typically describe what the term does.

Term	Class (what is it)	Features (what does the term do)
“A	is a soils lab test	that determines the amount of force needed to cause a shear failure in a soil sample.”

If the technical term has unclear or multiple meanings, add a qualifier to the beginning of the definition.

Qualifier	Term	Class (what is it)	Features (what does the term do)
“In aerodynamics	a	is a flight condition	in which the lift produced becomes less than the weight of the airplane, and the airplane stops flying.”

Tone refers to the feeling or attitude a document evokes; tone can also portray how the writer feels about a subject. Tone can be dependent on the purpose, audience, or medium of the message. Strive for neutral, professional, understandable words. Because engineers deal with complex information and terminology, word usage should be accessible and familiar.

Voice (Active or Passive)

Voice refers to how verbs are used in sentences. Although passive voice has long been a hallmark of technical writing, writing in the active voice is a preferred practice. Active voice makes documents more readable by making sentences more clear and concise. Passive voice is still used for certain types of technical documents such as lab reports.

When the verb is in the active voice, the subject performs the action; when the verb is used in the passive voice, the subject receives the action.

The boy hit the ball.

The ball was hit by the boy.

Hint: Watch for phrasing patterns common to passive voice: “was (verb)ed by….”

Use active voice when:

writing most technical documents.
writing needs to be concise, clear, and direct.
it is important to know the “doer” of the sentence.

Use passive voice when:

the genre (format) calls for passive voice (lab reports)
the action itself is more important than who or what performed the action or when the doer of the action is unknown.

Word Choice

Words should be used that are accessible and familiar to your audiences, both primary and secondary. This means using a shorter, more well-known word in place of a longer, less-known word with the same meaning.


Cognizant	Aware
Elucidate	Clarify
Aggregate	Total
Obfuscate	Confuse
Aranaceous	Sandy
Accumulate	Gather

Professional and Technical Writing/Instructions

1 Writing Instructions
2 Guidelines for Writing Instructions
3 Tailoring Instructions to the Intended Audience
4.1 Introduction
4.2 Description of Equipment
4.3 Materials/Equipment List
4.4 Procedure
4.5 Visual Aids
4.6 Troubleshooting
5 Usability Testing
6 General Writing Style Tips

Writing Instructions

Many people are used to following written instructions, but most people have never written instructions for another person. In many professional roles, you may have to write instructions. While some instructions may be simple and brief, other instructions may be more complex and take longer to complete. For this reason, it is important to know how to write useful instructions.

Writing useful instructions can be difficult because people read and comprehend things differently. For example, some people are visual learners and may have difficulty following written instructions. Readers also have a variety of educational backgrounds. When writing instructions, it is important to use a simple, logical style and format.

Guidelines for Writing Instructions

When writing instructions, avoid persuasive language and take a task-based approach. Keep the writing concise and clear, and focus on enabling the user to successfully accomplish the task.

In general, follow these guidelines:

Conciseness and Clarity

Keep sentences short and understandable. Use common terminology whenever possible. Avoid using idioms, slang, jargon, nicknames, abbreviations, and acronyms. If you do use terminology that might be new or confusing, then clearly define each term when it first appears in the instructions.

It is important to know your audience when writing instructions so that you include all necessary information and exclude unnecessary information. Knowing your audience allows you to make reasonable and well-informed assumptions based on the audience's likely background, experience, and familiarity with the subject. For example, if you are writing instructions for a group of senior citizens at the local branch of the public library, it may not be safe to assume that they are familiar with the basics of opening a specific software application. However, if you are writing instructions for a group of software developers within a professional organization, it may be safe to assume that they are familiar with the basics of opening a specific software application.

When deciding what information to include and exclude from instructions, it is important to clearly identify who your audience is and what their likely proficiency is with the topic of the instructions and related background information.

If an audience is likely to have a wide range of experience and knowledge that includes varying levels of familiarity and expertise, you can use various techniques to keep each set of instructions concise and focused on a single task, while still providing necessary information. For example, you can create separate instructions for prerequisite information and provide your audience with the means to quickly and easily access the separate instructions (through hyperlinks, appendices, etc.).

Pictures speak louder than words. Adding graphics to convey your thoughts may be more effective than the words themselves. Instructions that are well illustrated and accompany your written instructions are usually highly successful. It adds an extra level of understanding and allows the reader to skim or troubleshoot if problems occur. Pictures add an additional dimension that will allow your reader to visualize the end product. Also, when using graphics you should be mindful of those visual learners, and adapt the graphics.

Although pictures are great, you must be cautious not to include photographs or illustrations that are confusing or not associated with the actual written instructions. If you pair a poor picture with your instructions, you might cause the reader stress or introduce confusion when trying to decipher what you mean.

Also, when taking pictures, ensure that the area is well lit and the pictures are clear and bright. Dark or fuzzy pictures are often difficult to follow. Take care to photograph the subject in the same orientation each time to avoid confusion and consider using a tripod.

Size is also important when using images in instructions. A picture that is too small to see is just as useless as a blurry image.

To be powerful and understandable, your text and graphic for each step should clearly correlate to that step of the instructions.

Remember that the readers will actually be performing the task as they read along with the instructions. So you should not use solid blocks of small, hard to decipher text. Make sure to create a design and layout for your instructions page that will allow easy readability and add aesthetic quality. Keeping the page simple, but with a defined hierarchy, will assist the reader in completing the steps of the instructions.

When designing your page, a solid hierarchy is important for scan-ability. The use of bold headings, italics, and roman numerals will aid the reader in finding their place easily and helps with the overall visual appearance.

It is important for your instructions to be planned out in a logical progression. Make sure to state the problem clearly on the first page. Follow your problems with a set of specific steps detailing how to solve the proposed problem. Technical instructions must flow in a logical pattern. For example, when assembling a table it would not be good if you put the finishing touches on it before you had all the screws in place. As stated before, there should also be clear graphics where necessary to clarify the action. Remember, a picture is worth a thousand words.

Testing and Verification

We all know that instructions are difficult to write and that sometimes it sounds good on paper, but when you actually attempt to put the instructions to use, you might find that your wording makes no sense to others. Remember what might be common or obvious to you might baffle your readers, so know your audience. In addition to testing your instructions on yourself, have someone who knows nothing about your product test it. This is called a usability study. Take notes on what worked and what didn't and then revise your instructions accordingly. In the long run the more people that test your instructions, the more effective the final set will be.

Tailoring Instructions to the Intended Audience

Tailoring your instructions to the intended audience can be one of the most difficult tasks of your writing process. Before you begin your writing process you need to identify who your audience will be and how you can tailor your instructions to make them as understandable as possible. To help you do this, there are several questions you can ask yourself:

What background might your audience members have, and what prior knowledge might they possess? This will help you to determine what you will need to include or not include in your instructions.
What will their needs/interests be?
How will their demographics affect how you write? If the majority of your audience comes from a different demographic than you, you need to take into consideration language issues and make sure graphics are clear.
Is there a variability in your audience? If your audiences are composed of people with varied backgrounds, your writing should be tailored to the majority of your audience, and you may also consider adding additional information in appendices.

Based on your answers to the above questions, there are several ways you can ensure that your instructions will be as clear as possible to your readers.

Add information (such as tips, side notes) the readers will need in order to understand your instructions, and make sure no key information is missing.
Do not add information that is unnecessary; it may confuse or mislead your readers.
Make sure the document is at the level of your audience.
Add examples/graphics. Graphics can be very helpful to a reader.
Have a clear organization. Lack of organization creates confusion and frustration.

Writing Your Instructions

The following sections are descriptions of the different parts of the general superstructure of a set of instructions. What sections to include will vary based on the complexity of the instructions. Your document may contain any of the following sections:

Introduction

Description of equipment.

Materials and Equipment Necessary
The procedures
Visual aids

Troubleshooting

What is included in your introduction will depend on what your instructions are for and who will be using them. In any case, the introduction should be brief, but still informative. The introduction can include any or all of the following sections:

Subject/Aim: Here you should indicate the specific task that will be explained and what the outcome of the procedure will be.
Intended Readers: You may want to identify who the intended readers of the instructions are and if the reader will need additional knowledge or background in order to complete the task.
Scope: This will help the reader to know if the instructions will help them complete the task they want to or not.
Organization: Giving the reader an overview of what the rest of the instructions will look like can help them to more easily understand them. This section could also go under scope.
Safety: It is your responsibility to inform the readers of any hazards or dangers that could occur while they are completing the task. You need to display warnings in a clear and understandable fashion.

If there is equipment that the reader will have to use in order to operate or repair a piece of equipment, you may want to include a description of it.

Materials/Equipment List

Provide a list of equipment that the reader will need to accomplish the task so they know if they need additional tools or things they may not normally have. A list of supplies is also helpful for a reader to make sure that they have all the parts and pieces they need.

This section is obviously the most important part of an instructions set since it is the actual steps that the reader will follow to complete the task at hand. There are many ways to format the procedures, but most are done with numbered lists. The following are things you should do to make the steps clear and concise:

Give readers enough information to perform the step, avoid redundancy.
Put the steps in a list. Numbering often works the best.
Highlight key words.
Number steps.
Skip lines between steps.
Make actions stand out from the rest of the text.
Tell the reader what to do if they make a mistake. Not knowing what to do will cause frustration and the reader may give up on the task.

Visual Aids

The use of graphics and pictures to correspond to each step is highly recommended. Each person has different learning habits; some like texts while others are better off with pictures. The presence of graphics also allows the reader to make sure he/she is still on the right track. In most situations it would be beneficial to have a combination of both graphics and words.

Instructions should include this section to tell the reader what to do if something goes wrong during the building process or if the completed project does not look like the expected outcome. Putting this information into a table format often works the best.

For an example set of instructions visit [1] This webpage contains information from the textbook entitled Power Tools for Technical Communication by David A. McMurrey.

Usability Testing

Usability testing is an absolutely crucial step in preparing an effective set of instructions. Once you have completed a draft of your instructions, it is important to test them to see where improvements can be made. A usability test should be performed on multiple testers for each updated draft of your instructions. Here is how you go about performing a usability testing:

1. First, you should choose your testers from a group that is representative of your intended audience. In order to single these specific users out, you may need to ask a few preliminary questions. For example, asking what their experience level with the task is or what their job field is.

2. Next you need to choose how you will evaluate the tester's performance in completing the task. There are different methods to choose from, but one method is called the "Think Aloud" method. When using this method you ask your tester to complete the task using your instructions while verbalizing everything that is going through their head as they go through the instructions. Do not offer any help to the tester as he or she goes through the test, kindly tell them that you can answer their questions at the end. As the tester says what is confusing or hard you take notes. You can record this information in a chart that has three columns. In the first column you will record the problems your tester had. In the second column you write down what the possible cause of each problem was. In the third try to generate a possible solution to the problem or possible ways you can change your instructions to make them more understandable. Be sure to be descriptive in what you want to find out. Be sure to lay out the testing form to collect all pertinent information about your testing so no information is overlooked or misplaced.

3. After the test is done look at your notes and ask the tester to elaborate on the problems that you noted. This is an important step because you are getting direct feedback from your audience. Make sure that you understand exactly what was confusing for them, as this will help you in writing the most successful set of instructions. Ask testers how you could change that step or part of the instructions to make them unambiguous.

4. Based on your findings edit and update your instructions. After you do so they should be more understandable and easier to follow for your intended audience. In many cases it is appropriate or even necessary to conduct one or more rounds of usability tests as you perfect your instructions. More testing may prove beneficial in discovering problems that were overlooked the first round of testing or because the problems may have been masked by original complications. If time permits, be sure to run as many rounds of usability testing as needed.

Note: Pay special attention to your intended audience and ensure that you have the number of testers, and accurate demographics necessary to accurately represent your sample. For example, if you are making instructions for a 'beginner audience' and test an all 'expert' audience your sample will not be representative. In addition, if you are wanting to make instructions for a large audience of several ages, gender and experience level, your sample will need to be large and representative of that population.
If the instructions require the tester to use both hands (like tying a tie), consider making all the instructions visible without turning pages so it is easier for them to complete the task.

General Writing Style Tips

Many people resist reading instructions. They try to figure out for themselves how to operate a product or perform a task and will turn to the instructions only if all their efforts fail. When they do read the instructions, they want to understand everything immediately without having to read anything twice. A simple design, plain wording, and clear instructions will be critical to encouraging readers to pay attention to your instructions or procedures.

When writing technical documents and instructions there are several style tips you should keep in mind:

Use a lot of imperative, command or direct address, kinds of writing. It is OK to use "you" when writing instructions, because you are addressing the reader directly.
Use active instead of passive voice.
Do not leave out articles such as a, an and the.
Use action verbs.
Ensure graphics match descriptive text to avoid confusion.
Label graphics by steps, for example Step 17 "...Put...", the graphic should be labeled clearly with a number "17" or if multiple graphics exists for a line of text writing in chronological order "17a, 17b, etc." or if different views "17 front, 17 back, etc."
Keep text short but descriptive.
Avoid complicated jargon, use simple verbiage to ensure understanding by a broad spectrum of users.
Use concise headings and subheadings to describe and highlight each section.
Leave plenty of white space around headings.
Highlight safety information and warnings.
Keep illustrations as simple as possible.

Book:Professional and Technical Writing

7.7 Writing Instructions

One of the most common and important uses of technical writing is to provide instructions, those step-by-step explanations of how to assemble, operate, repair, or do routine maintenance on something. Although they may seems intuitive and simple to write, instructions are some of the worst-written documents you can find. Most of us have probably had many infuriating experiences with badly written instructions. This chapter will show you what professionals consider the best techniques in providing instructions.

An effective set of instruction requires the following:

Clear, precise, and simple writing
A thorough understanding of the procedure in all its technical detail
The ability to put yourself in the place of the reader, the person trying to use your instructions
The ability to visualize the procedure in detail and to capture that awareness on paper
Willingness to test your instructions on the kind of person you wrote them for.

Preliminary Steps

At the beginning of a project to write a set of instructions, it is important to determine the structure or characteristics of the particular procedure you are going to write about. Here are some steps to follow:

1. Do a careful audience and task analysis

Early in the process, define the audience and situation of your instructions. Remember that defining an audience means defining the level of familiarity your readers have with the topic.

2. Determine the number of tasks

How many tasks are there in the procedure you are writing about? Let’s use the term procedure to refer to the whole set of activities your instructions are intended to discuss. A task is a semi-independent group of actions within the procedure: for example, setting the clock on a microwave oven is one task in the big overall procedure of operating a microwave oven.

A simple procedure like changing the oil in a car contains only one task; there are no semi-independent groupings of activities. A more complex procedure like using a microwave oven contains several semi-independent tasks: setting the clock; setting the power level; using the timer; cleaning and maintaining the microwave, among others.

Some instructions have only a single task, but have many steps within that single task. For example, imagine a set of instructions for assembling a kids’ swing set. In my own experience, there were more than a 130 steps! That can be a bit daunting. A good approach is to group similar and related steps into phases, and start renumbering the steps at each new phase. A phase then is a group of similar steps within a single-task procedure. In the swing-set example, setting up the frame would be a phase; anchoring the thing in the ground would be another; assembling the box swing would be still another.

3. Determine the best approach to the step-by-step discussion

For most instructions, you can focus on tasks, or you can focus on tools (or features of tools). In a task approach (also known as task orientation) to instructions on using a phone-answering service, you’d have these sections:

Recording your greeting
Playing back your messages
Saving your messages
Forwarding your messages
Deleting your messages, and so on

These are tasks—the typical things we’d want to do with the machine.

On the other hand, in a tools approach to instructions on using a photocopier, there likely would be sections on how to use specific features:

Copy button
Cancel button
Enlarge/reduce button
Collate/staple button
Copy-size button, and so on

If you designed a set of instructions on this plan, you’d write steps for using each button or feature of the photocopier. Instructions using this tools approach are hard to make work. Sometimes, the name of the button doesn’t quite match the task it is associated with; sometimes you have to use more than just the one button to accomplish the task. Still, there can be times when the tools/feature approach may be preferable.

4. Design groupings of tasks

Unpacking and setup tasks
Installing and customizing tasks
Basic operating tasks
Routine maintenance tasks
Troubleshooting tasks.

Common Sections in Instructions

The following is a review of the sections you’ll commonly find in instructions. Don’t assume that each one of them must be in the actual instructions you write, nor that they have to be in the order presented here, nor that these are the only sections possible in a set of instructions.

For alternative formats, check out the example instructions .

Introduction: plan the introduction to your instructions carefully. It might include any of the following (but not necessarily in this order):

Indicate the specific tasks or procedure to be explained as well as the scope (what will and will not be covered)
Indicate what the audience needs in terms of knowledge and background to understand the instructions
Give a general idea of the procedure and what it accomplishes
Indicate the conditions when these instructions should (or should not) be used
Give an overview of the contents of the instructions.

General warning, caution, danger notices : instructions often must alert readers to the possibility of ruining their equipment, screwing up the procedure, and hurting themselves. Also, instructions must often emphasize key points or exceptions. For these situations, you use special notices —note, warning, caution, and danger notices. Notice how these special notices are used in the example instructions listed above.

Technical background or theory: at the beginning of certain kinds of instructions (after the introduction), you may need a discussion of background related to the procedure. For certain instructions, this background is critical—otherwise, the steps in the procedure make no sense. For example, you may have had some experience with those software applets in which you define your own colors by nudging red, green, and blue slider bars around. To really understand what you’re doing, you need to have some background on color. Similarly, you can imagine that, for certain instructions using cameras, some theory might be needed as well.

Equipment and supplies: notice that most instructions include a list of the things you need to gather before you start the procedure. This includes equipment , the tools you use in the procedure (such as mixing bowls, spoons, bread pans, hammers, drills, and saws) and supplies , the things that are consumed in the procedure (such as wood, paint, oil, flour, and nails). In instructions, these typically are listed either in a simple vertical list or in a two-column list. Use the two-column list if you need to add some specifications to some or all of the items—for example, brand names, sizes, amounts, types, model numbers, and so on.

Discussion of the steps: when you get to the actual writing of the steps, there are several things to keep in mind: (1) the structure and format of those steps, (2) supplementary information that might be needed, and (3) the point of view and general writing style.

Structure and format: normally, we imagine a set of instructions as being formatted as vertical numbered lists. And most are in fact. Normally, you format your actual step-by-step instructions this way. There are some variations, however, as well as some other considerations:

Fixed-order steps are steps that must be performed in the order presented. For example, if you are changing the oil in a car, draining the oil is a step that must come before putting the new oil. These are numbered lists (usually, vertical numbered lists).
Variable-order steps are steps that can be performed in practically any order. Good examples are those troubleshooting guides that tell you to check this, check that where you are trying to fix something. You can do these kinds of steps in practically any order. With this type, the bulleted list is the appropriate format.
Alternate steps are those in which two or more ways to accomplish the same thing are presented. Alternate steps are also used when various conditions might exist. Use bulleted lists with this type, with OR inserted between the alternatives, or the lead-in indicating that alternatives are about to be presented.
Nested steps may be used in cases when individual steps within a procedure are rather complex in their own right and need to be broken down into sub-steps. In this case, you indent further and sequence the sub-steps as a, b, c, and so on.
“Step-less” instructions . can be used when you really cannot use numbered vertical list or provide straightforward instructional-style directing of the reader. Some situations must be so generalized or so variable that steps cannot be stated.

Supplementary discussion: often, it is not enough simply to tell readers to do this or to do that. They need additional explanatory information such as how the thing should look before and after the step; why they should care about doing this step; what mechanical principle is behind what they are doing; even more micro-level explanation of the step—discussion of the specific actions that make up the step.

The problem with supplementary discussion, however, is that it can hide the actual step. You want the actual step—the specific actions the reader is to take—to stand out. You don’t want it all buried in a heap of words. There are at least two techniques to avoid this problem: you can split the instruction from the supplement into separate paragraphs; or you can bold the instruction.

Writing Style

Placing the key user steps in bold can a very helpful way to signal clearly what the reader needs to do. Often the command verb is bolded; sometimes bold font highlights the key component being discussed.

Use of the passive voice in instructions can be problematic. For some strange reason, some instructions sound like this: “The Pause button should be depressed in order to stop the display temporarily.” Not only are we worried about the pause button’s mental health, but we wonder who’s supposed to depress the thing ( ninjas ?). It would be more helpful to indicate when the reader must “ press the Pause button.” Consider this example: “The Timer button is then set to 3:00.” Again, one might ask, “is set by whom? Ninjas ?” The person following these instructions might think it is simply a reference to some existing state, or she might wonder, “Are they talking to me?” Using the third person can also lead to awkwardness: “The user should then press the Pause button.” Instructions should typically be written using command verb forms and using “you” to make it perfectly clear what the reader should do.

Illustrating Your Instructions

Perhaps more than in any other form of technical writing, graphics are crucial to instructions. Sometimes, words simply cannot explain the step. Illustrations are often critical to the readers’ ability to visualize what they are supposed to do. Be sure that the graphics represent the image from the reader’s perspective.

Formatting Your Instructions

Since people rarely want to read instructions, but often have to, format your instructions for reluctant readability. Try to make your reader want to read them, or at least not resistant to the idea of consulting them. Highly readable format will allow readers who have figured out some of the instructions on their own to skip to the section where they are stuck. Use what you have learned about headings , lists , visuals , and passive space to create effective and readable instructions:

Headings : normally, you’d want headings for any background section you might have, the equipment and supplies section, a general heading for the actual instructions section, and subheadings for the individual tasks or phases within that section.

Lists : similarly, instructions typically make extensive use of lists, particularly numbered vertical lists for the actual step-by-step explanations. Simple vertical lists or two-column lists are usually good for the equipment and supplies section. In-sentence lists are good whenever you give an overview of things to come.

Special Notices : you may have to alert readers to possibilities in which they may damage their equipment, waste supplies, cause the entire procedure to fail, injure themselves or others—even seriously or fatally. Companies have been sued for lack of these special notices, for poorly written special notices, or for special notices that were out of place. See special notices for a complete discussion of the proper use of these special notices as well as their format and placement within instructions.

As you reread and revise your instructions, check that they do the following:

Clearly describe the exact procedure to be explained
Provide an overview of content
Indicate audience requirements
Use various types of lists wherever appropriate; in particular, use numbered lists for sequential steps
Use headings and subheadings to divide the main sections and subsections in a logical, coherent order
Use special notices as appropriate
Use graphics to illustrate key actions and objects
Provide additional supplementary explanation of the steps as necessary
Create a section listing equipment and supplies if necessary.

Share This Book

Purdue Online Writing Lab Purdue OWL® College of Liberal Arts

Professional, Technical Writing

Welcome to the Purdue OWL

This page is brought to you by the OWL at Purdue University. When printing this page, you must include the entire legal notice.

Copyright ©1995-2018 by The Writing Lab & The OWL at Purdue and Purdue University. All rights reserved. This material may not be published, reproduced, broadcast, rewritten, or redistributed without permission. Use of this site constitutes acceptance of our terms and conditions of fair use.

In this section

Subsections.

Want to create or adapt books like this? Learn more about how Pressbooks supports open publishing practices.

Writing Essays

Dawn Atkinson

The current chapter focuses on essays , pieces of persuasive writing developed around defined topics. This genre’s persuasiveness rests in large part on its logical structure, inclusion of quality evidentiary support, and consistent design, as explained herein; hence, essay writing calls for planning, researching, synthesizing, and revising. Although essays are generally considered a form of academic rather than technical writing, the division is not absolute, and the prevalence of essay assignments in both writing and other university-level courses merits our focus on them here.

While reading this chapter, keep in mind that college essays typically require use of a formal writing style, although the specifics may vary depending on the particular assignment and area of study. For an overview of formal writing guidelines, see the George Mason University Writing Center’s (2017) handout entitled “Reducing Informality in Academic Writing” ( https://writingcenter.gmu.edu/guides/reducing-informality-in-academic-writing ).

Essays can be divided into two broad types: expository and argumentative essays. To define these categories using information adapted from Student Academic Success Services, Queen’s University (2018b, para. 13), expository essays explain—they teach, illustrate, or clarify a subject for a reader—while argumentative essays make claims and seek to convince a reader to accept a position or point of view.

Focusing an Essay

For an essay topic to be manageable, its focus must be narrow enough so that it can be addressed adequately within the word or page count available; however, the topic should not be so narrow so as to impede your research efforts. When deciding on a topic, conduct initial research using library or internet resources to get a sense of current scholarship in the area, as well as points of agreement and contention, which may lead you to a focused direction for research. To pinpoint your particular interest in a topic, you might also consider using listing, mind mapping, outlining, freewriting, looping, or questioning, the brainstorming strategies described in the “Maintaining a Productive Writing Schedule” chapter of this textbook. Talking with your instructor or a librarian about a topic may also help you decide a paper’s focus.

What other methods could you use to narrow the focus of an essay?

Figure 1, a multi-page handout adapted from the Writing and Communication Centre, University of Waterloo (n.d.a, pp. 2-3), illustrates the process of narrowing an essay topic.

Developing and Narrowing a Topic

Develop and Narrow a Topic

A well-written paper depends on a strong topic that is focused and specific. To get there, you need to develop some topic ideas, choose the best one, and narrow that topic further.

Developing A Topic

Researching your subject, brainstorming ideas, and sharing your ideas with others are three steps that can help you develop a strong topic.

Do your research

Doing preliminary research will help you to discover what people who work on the topic are interested in or concerned about.

There are countless ways to brainstorm ideas for a topic; below are three common approaches.

Freewriting: Jot down ideas without revising or proofreading
Questioning: Write down questions you have about your topic without revising or proofreading
Mapping: Starting with a main topic, write down subtopics that come to mind, drawing links that show how the different subtopics relate.

Talk about your ideas

Talking to others helps you to understand your ideas from a reader’s perspective. It can help you refine the topic or even move in a new direction.

Narrowing Your Topic

Narrowing your topic makes your work more manageable and your paper more likely to succeed. A good paper takes a smaller portion of a larger issue or problem and investigates that part in depth. Narrowing your topic allows you to choose a problem that is specific enough to research with vigour. Below is an example of the process:

Move from abstract to concrete

A manageable topic is concrete. As we narrow the scope of a topic, the subject matter moves from abstract concepts to ideas that are more precise. Let’s use bicycles, again, as our example.

Main topic: Bicycles

Subtopics: Design, Safety, Health impacts, Charity drives, Bicycle usage, Bicycles and education, Reuse, Infrastructure, Environmental impacts, Policies, Bicycles and urban development, Bicycles and commercial products, Bicycle culture

Although bicycles are concrete “things,” the word bicycles could mean different things to different people. These ideas, such as design, bicycle culture, or infrastructure, are subtopics of “bicycles.”

Add specific details

As you narrow in on one subtopic, the number of subtopics decreases:

Revised main topic: Bicycles and policies

safety standards for bicycle design
safety gear policies
urban development policies and bike lanes
road policies and cyclists

Tip: Is it narrow enough? In our last example, notice that when you begin to narrow a large topic, the initial subtopics that come up are still broad, general ideas. The more you narrow, the more specific your descriptions become. You can use the traditional journalistic questions (Who, What, Where, When, Why) to help you move towards more specific topics:

road building policies?
building zone policies?
other infrastructure?
metropolitan areas?
medium-sized cities?
small cities?
construction companies?
planning committees?

Using these questions to target the subject matter, we might narrow the topic, bicycle lanes and urban development , even further to the following: policies related to bike lanes in mid-sized metropolitan areas .

As the handout illustrates, deciding upon a suitably narrow essay topic is a process that may require several attempts to complete. Regardless, devoting time to this initial planning process is a wise investment since a defined essay topic will usefully guide a paper’s development.

Structuring an Essay

Essays, like letters and memos, follow an introduction, body, and conclusion structure, although these sections may also be subdivided. The sections need to be fully developed to coherently deliver an essay’s central message to readers. They also need to be proportionate to an essay’s overall length: for instance, a brief essay requires a brief introduction and conclusion, whereas an extended essay can accommodate a longer introduction and conclusion. In general, budget 10 percent of the paper’s word count for the introduction, 80 percent for the body, and 10 percent for the conclusion.

Composing an Introduction Section

An essay introduction establishes context for the reader by commencing discussion of the document’s central message, around which all the other content will coalesce, and by revealing how the essay will unfold. To be more specific, the introduction delimits the scope and purpose of the essay so that readers understand its direction, range of coverage, and intent.

The context-setting information provided at the beginning of an introduction might include definitions of key terms that will be used throughout the rest of the paper, a summation of how something works, essential background on the topic to be addressed in the piece, or articulation of circumstances pertinent to a problem—perhaps a concise discussion of historical events surrounding the topic, previous research conducted in the area, or treatment of the topic in the news. A writer has considerable leeway when deciding how to articulate context-setting information, and inventiveness in this section can help draw readers into the essay. Schall (2014, para. 7), for instance, describes how narration , storytelling in other words, can be used to stimulate reader interest in an essay. The following examples, adapted from Schall (para. 7), present the initial lines from two essay openings, one focused on the “generic nature of America’s highway exit ramp services” and the other on shape constancy in relationship to human visual perception, to demonstrate the interest that narration can inspire.

The observation struck me slowly, a growing sense of déjà vu. I was driving the endless miles of Interstate 70 crossing Kansas when I began to notice that the exits all looked the same. → Notice how the writer uses I to communicate his/her experience.
Our eyes often receive pictures of the world that are contrary to physical reality: a pencil in a glass of water miraculously bends and railroad tracks converge in the distance. → Notice how writer omits I but is nevertheless reflective about the subject matter.

Regardless of the flavor of context-setting information you provide in an essay, the information should help readers connect with the text’s central message. Therefore, avoid beginning an essay with an overly general statement, such as “People argue about many controversial topics,” that could apply to any number of papers. This kind of nondescript material wastes readers’ time.

An essay’s central message is delivered in its thesis statement , a sentence, sometimes more, that articulates the theme of the paper and the writer’s view on it. The thesis thus explains the paper’s controlling idea by specifying what the writer has to say about a particular topic and by clarifying what will and will not be covered. The thesis statement is typically placed at or near the end of the introduction to initiate the reader’s progression into the rest of the paper. Schall (para. 8) explains that a well-written thesis statement should be inexorably tied to the essay it accompanies, carefully constructed, and revealingly focused: “concretely announce the most important elements of your topic and suggest your fundamental approach—even point [readers] toward the paper’s conclusion if you can.” The following two thesis statement examples, adapted from Schall (para. 9), fit this description.

This paper reviews the problem of Pennsylvania’s dwindling landfill space, evaluates the success of recycling as a solution to this problem, and challenges the assumption that Pennsylvania will run out of landfill space by the year 2024.
As this paper will show, the fundamental problem behind the Arab-Israeli conflict is the lack of a workable solution to the third stage of partition, which greatly hinders negotiations for peace.

Notice that each example indicates the paper’s unifying theme and the writer’s viewpoint on the matter.

Developing an effective thesis statement for an essay requires work on a writer’s part. Try using these steps, adapted from the Writing and Communication Centre, University of Waterloo (n.d.c, “Building Effective Thesis Statements”), when building a thesis statement to make the task more straightforward.

Read the assignment directions carefully so you are clear about the expectations.
Conduct preliminary research to gather and organize information about your topic.
What is new about this topic?
What is important about this topic?
What is interesting about this topic?
What have others missed in their discussions about this topic?
Conduct additional research once you have narrowed your focus in order to find evidence to support your thesis. As you research, your understanding of the topic may further develop and evolve.
Refine your thesis statement so it clearly expresses your angle or position.

As this list points out, an effective thesis statement typically develops over time and with concerted effort.

A thesis statement should fulfill the functions set out in its definition otherwise it will not guide the development of an essay. The following list, adapted from McKeever (n.d.c, paras. 12, 16, 17) and Sweetland Center for Writing, University of Michigan (2020a, para. 8), identifies markers of weak thesis statements.

A simple observation (Example: NASA scientists regularly conduct experiments in space.) Although an observation may be true, it cannot initiate a lively and extended discussion of the multiple views surrounding a complex topic.
A statement of fact (Example: Some people are opposed to stem cell research.) To determine whether a statement is a fact, ask if anyone could reasonably disagree with it. If everyone would agree that the statement is true, it is a fact, meaning that it is not open to interpretation or discussion.
A broad generalization (Example: Politics requires working for the people.) It may seem that a broad thesis statement creates the possibility for numerous essay directions, but broad issues contain too many specific arguments within them, and making a broad claim leads to making a shallow argument.
A question (Example: Why are self-service checkout machines popular in stores?) A thesis must be phrased as a statement, although you might decide to narrow the focus of an essay by devising a research question (a question that a research project seeks to answer). A thesis statement answers a research question in sentence form.
A misleading statement (Example: This essay will prove that a person who is old enough to vote and serve in the armed forces should be allowed to drink alcohol too.) The word prove points to a fact, something that is indisputable, and a thesis cannot be a statement of fact. More troubling about the example, however, is that an essay cannot irrefutably prove something, so the statement is misleading.
A statement that uses figurative language (Example: The runaway train of individualism must be controlled and not allowed to jump the tracks and obliterate innocent bystanders.) A thesis statement should enable a reader to clearly and immediately identify the focus of an essay. Figurative language, such as that used in the example, is wordy, vague, and quite frankly confusing, so avoid it.
An unfocused statement (Example: I think the inconsistent penalties for drunk driving, even if enhanced, because of the impact of drinking and driving on families who lose their children, fathers, mothers, or other family members to death and/or disability, are not strict enough in the various states, allowing drunk drivers to go free although there is a high risk of offending again.) A thesis statement that contains multiple clauses and lists is confusing. Oftentimes, such statements also present details that should be discussed in body paragraphs. Remember that a focused thesis statement identifies and delimits the direction of an essay, as this revised example does: The United States needs a consistent, national law that strips drunk drivers of driving privileges for five years after their first offense. Notice that the revised example omits I think since the phrase is redundant; the writer’s view is implicit in the sentence. In general, avoid the phrases I think , I feel , and I believe since they add unnecessary words to an essay and give the appearance of uncertainty.

Prevent the thesis statement problems listed by focusing on a specific topic and articulating your view on that topic in a clear, concise, and unambiguous way. In addition, be prepared to revise the thesis statement as necessary during your essay’s development.

Depending on assignment specifications, disciplinary conventions, educational context, or authorial choice, a writer may integrate a route map , a brief outline of the specific topics the essay will cover and in what order, in the thesis statement or provide this information in a separate sentence or sentences at the end of the introduction. The order of topics in the route map should match the sequence in which they are addressed in the body of the essay; the route map thus serves as a skeleton outline of the essay by giving readers a sense of how the text will be organized.

The essay introduction structure described here takes the form of the inverted triangle presented in Figure 2, with the reader connecting with broad context-setting information before moving on to a more narrow discussion of the essay’s focus area and organizational structure provided in a thesis statement and route map.

Upside down triangle images showing: Context-setting/background information to Thesis statement to Route Map

Figure 2. Moving from general to specific information as an essay introduction proceeds

Figure 3, adapted from the Academic Writing Help Centre, Student Academic Success Service at the University of Ottawa (2016c, para. 10), shows the introduction elements at work in a sample paragraph.

Image of essay. Why is industrial expansion more important than the survival of valuable ecosystems? Last year, that kind of priority resulted in the death of 600,000 red-tailed swallows in Ungolu. While environmentalists protest the destruction of the Ungolu rainforest for the sake of its wildlife, and particularly for the sake of the red-tailed swallow, the inhabitants of the area demand more land for cattle and living space and require more wood to generate revenue. Although the residents insist their society depends on logging practices, this does not justify the effects of these practices. Without a change in policy, the red-tailed swallow will most likely disappear in just a few years. The extinction of this species must be prevented because it would have a devastating impact on the Ungolu rainforest. As this paper will show, the clear-cutting of the rainforest has already eliminated much of the natural habitat of the red-tailed swallow, thus reducing the population growth rate of a species that plays a vital part in maintaining the balance of the ecosystem. Its extinction would result not only in the destruction of the rainforest, but in the destruction of the ecology that it shelters in as well. Moreover, the extinction of the red-tailed swallow is unnecessary—there are more ecological and long-lasting ways to ensure the economic development of Ungolu than logging.

Figure 3. An introduction with context-setting, a thesis statement, and a route map

If an introduction is clearly focused, comprehensibly organized, and grammatically and mechanically sound, it can inspire a reader’s interest in the remainder of the essay.

Composing a Body Section

The body of an essay expounds upon the central theme articulated in the text’s thesis statement until that theme is fully developed. The body section is divided into paragraphs, and each paragraph centers on one main point that unifies the content of the paragraph and is articulated through an explicit or implied topic sentence. A topic sentence encapsulates a paragraph’s focus, and in technical writing, explicit topic sentences typically appear at the beginnings of paragraphs to expediently deliver needed information to readers. Using this structure, everything that follows the topic sentence in a paragraph—examples, illustrations, explanations, quotations, paraphrases, summaries, reasons—supports the point made in the topic sentence. If a writer instead opts to use an implied topic sentence, he or she may discuss a source, viewpoint, question, or piece of evidence slowly in the paragraph, allowing the paragraph’s momentum to develop the text’s key takeaway. The reader is consequently responsible for inferring the paragraph’s topic sentence in this situation. Whether the topic sentence is explicit or implied, the reader should leave the paragraph with a clear understanding of its main point.

To successfully communicate a paragraph’s main point and give readers a sense of the paragraph’s direction, a topic sentence must be specific. A topic sentence that simply announces the subject matter of a paragraph—“In this paragraph, I will discuss…”—does not fit this description, as the professionals at Student Academic Success Services, Queen’s University (2018a, para. 5) explain. To devise a precise alternative, think carefully about the paragraph’s key takeaway and how that point ties in with surrounding paragraphs and ultimately links back to the essay’s thesis statement; then try to articulate the key takeaway in one focused and unifying umbrella sentence underneath which all the other points in the paragraph fall.

In the process of developing an essay’s central theme through the inclusion of focused topic sentences and relevant and substantive follow-up sentences, the body section of an essay aims to be compelling: for example, an author might try to convince readers to adopt his or her position on an issue; to take a careful look at a text and how it is constructed; to contemplate the layers of complexity surrounding an area of investigation; or, more generally, to consider the well-informed nature of the essay and its fluid delivery of information. The body section thus involves persuasion. To address an essay’s central theme in a comprehensive and fair way, a writer who aims for maximum persuasiveness will speak to the multifaceted perspectives surrounding points of discussion rather than focusing exclusively on his or her own viewpoint. The latter signals bias in an argument, a situation to avoid in academic and technical writing.

Writers may employ certain patterns of development to present information in body paragraphs so that it is logical and compelling. The following list, adapted from Student Academic Success Services, Queen’s University (2018b, paras. 12, 17-21), describes a number of these patterns.

Description: Conveys specific details about the look, taste, smell, sound, or feel of something.
Illustration/Example: Illustrates a general concept with specific examples or uses an example as evidence to support a point.
Spatial: Describes how something looks in relationship to how it occupies space (e.g., inside to outside, top to bottom, front to back, or left to right).
Comparison/Contrast: Examines two or more things to determine their similarities and differences using clearly defined criteria.
Cause/Effect: Examines the causes that have led to certain results.
Evaluation: Measures something by examining it in relation to a given set of criteria; may discuss the thing’s strengths and weaknesses in light of this evaluation.
Classification: Examines something by dividing it into categories or subtypes.
Sequence/Process: Explains how something works in sequential or step-by-step fashion.
Narration: Tells a story in chronological order.
Definition: Explains the distinguishing features of something.
Order of Importance: Places the most important information in a strategic place to affect reader perception.

Writers may combine these patterns when developing body paragraphs or use them separately; assignment directions may also specify the use of a particular pattern in an essay.

Figure 4, adapted from the Academic Writing Help Centre, Student Academic Success Service at the University of Ottawa (2016a, para. 11), demonstrates elements of persuasion at work—in this case a viewpoint (claim) supported with a reason and evidence—in an argumentative body paragraph.

What do you think of the paragraph? Apart from the argument elements identified in the paragraph, what else helps to make it persuasive?

Figure 4. A body paragraph containing a claim supported with a reason and evidence

While Figure 4 uses a quotation as evidence to support a claim, evidence in body paragraphs can take many forms: for example, summaries, paraphrases, tables, figures, equations, anecdotes, personal experiences, facts, statistics, and numerical and word field data.

Composing a Conclusion Section

A conclusion emphasizes an essay’s central message by reiterating its thesis (without repeating it word for word) and summarizing its key points. Because a conclusion brings an essay to a cohesive end, it should not discuss new information; instead, it should follow on logically from content already covered. A conclusion’s very definition—“an articulated conviction arrived at on the basis of the evidence you have presented” (Schall, 2014, para. 15)—points to its unifying function. The following conclusion sample, adapted from Schall (para. 16) and excerpted from the paper “Exercise in the Prevention and Treatment of Osteoporosis in Women,” reflects directly on the paper’s hypothesis, stated in the introduction, and presents a logical realization of the paper’s goals.

The majority of evidence presented in this paper supports the hypothesis that exercise positively affects bone mineral density in both premenopausal and postmenopausal women. Importantly, exercise has been shown to increase bone mineral density in premenopausal women even after the teenage years, and it helps preserve the bone mass achieved in the subsequent decades. Evidence also shows that exercise adds a modest amount of bone mass to the postmenopausal skeleton. As these findings demonstrate, women of all ages can benefit from regular weight-bearing exercise, an increased intake of calcium-rich foods, and—for postmenopausal women—the maintenance of adequate estrogen levels. Women of all ages can prevent osteoporosis or lessen its severity by making appropriate lifestyle choices.

If you experience a roadblock when constructing a coherent conclusion such as this, Schall (para. 14) recommends reviewing the essay’s introduction and body to revisit what the paper set out to do and how it accomplished its aims or reviewing these sections to determine the paper’s contributions to the particular research area addressed.

While focusing squarely on the essay’s central message and the document’s particular purpose, a conclusion may also discuss how the essay’s findings compare with other research in the area; emphasize the implications of the findings (what they mean and why they are important—the so what , in other words); consider the limitations of the research conducted for the essay; or make recommendations for further research. Again, these elements should link back to the essay’s central message so readers understand the context for their discussion. Here is a conclusion example, adapted from the Academic Writing Help Centre, Student Academic Success Service at the University of Ottawa (2016b, para. 7), that emphasizes the essay’s central message and summarizes its key points before underscoring the implications of the findings and proposing a solution to the issue discussed in the paper.

In the end, there is no way to deny the seriousness of the environmental threat. If the current clear-cutting practices continue, the Ungolu rainforest will be unable to support the red-tailed swallow, and it will become extinct. Without this bird, the tree-eating corkscrew beetle will have nothing to stop its spread, and it will disrupt the rainforest’s ecosystem even further. Although the inhabitants of the area request the commercialization of land and wood to encourage the economic development of Ungolu, initiatives with regard to ecotourism and biological agriculture can be pursued to ensure both the growth of the economy and the survival of the red-tailed swallow. Because of the dire environmental consequences of its extinction, it is vital that this species be preserved—and it is possible to do so with a reasonable amount of effort and resources. Indeed, the best way to encourage the inhabitants of the area to let the Ungolu rainforest recover is for northern countries to stop purchasing the products obtained from logging practices and to subsidize the local initiatives discussed in this paper, otherwise the local population will not be motivated to make a significant change. Without quick and decisive action, rainforest tracts will be eliminated, and the inhabitants of the area will be even worse off than before the introduction of logging.

The implications and call to action discussed in this conclusion coherently link back to the introduction and body sections of the essay.

Gathering Quality Evidence for an Essay

In addition to a logical structure, an essay’s effectiveness largely hinges on the quality of its evidentiary support. Evidence that is inaccurate, untrustworthy, irrelevant, insufficient, dated, or flawed in some other way is unlikely to convince a reader to adopt a writer’s perspective and may actually inspire the opposite effect. On the other hand, sound evidence can contribute to the persuasiveness of an essay and demonstrate a writer’s research ability. While the “Writing Topic Proposals” chapter of this textbook supplies tips for evaluating the quality of sources and the evidence they provide, the multipage handout in Figure 5 (adapted from McKeever, n.d.a) offers additional points to consider.

Does anything on the handout surprise you? Why or why not?

Figure 5. A guide to evaluating information sources

You might decide to use the checklist items in Figure 5 to evaluate sources of information for your essay. Figure 6 (Webber, 2018, p. 1) presents an alternative tool: a visual scorecard for source evaluation.

Figure 6. A scorecard tool for evaluating source information

The instruments in figures 5 and 6 can help you apply consistent evaluation criteria to potential sources of evidentiary information for an essay.

Incorporating Quality Evidence into an Essay

After locating quality evidentiary support for an essay, you must incorporate it into your text in a logical and ethical way so that readers understand its presence, its origin, and how it relates to your own ideas. Quotation, paraphrase, and summary offer three means by which to integrate evidence into an essay.

Before attempting to quote, paraphrase, or summarize a source, make sure you fully understand the text’s meaning and feel confident about discussing it. If you are unclear about what the source text says, do not try to integrate its information into your essay; such confusion can damage the persuasiveness of a paper since savvy readers may detect the issue. Instead, read the text several times slowly to grasp its meaning or discuss it with your classmates and instructor before attempting to incorporate its information into an essay. Class discussions about confounding texts can oftentimes provide clarification and fruitful avenues for writing projects.

Using Quotations

When writers quote , they use the exact words from source texts, enclose those words in quotation marks, and cite and reference the sources to document the origin of information. Quotations can provide telling evidence in a paper if they are used sparingly and strategically. Conversely, their overuse can affect the flow of a piece of writing and give readers the impression that the writer cannot formulate his or her own thoughts about a text. Table 1 explains when to use and avoid quotations.

Table 1. Reasons to use and avoid quotations when writing


When the language of a source is the focus of your project or investigation	When the quotation repeats rather than expands on the point you are making
When a text’s language is especially expressive	When you simply want to fill space
When the precise words of an authority give credence to your argument	When the quotation makes rather than supports your point
When exact wording is necessary for technical accuracy	When you cannot weave the quotation into your own text in a cohesive manner

If you decide to use quotations in an essay, take care to integrate them cohesively.

Quotations cannot on their own provide compelling evidentiary support for an essay; a writer must consequently explain their presence and relevance to readers. In other words, a writer must contextualize a quotation so readers understand its use. The quotation sandwich offers a helpful method for working quotations into papers in a cohesive way. Using this technique, a writer introduces a quotation, provides the quotation, and comments on the quotation’s relationship to the paper. Figure 7, adapted from McKeever (n.d.b), demonstrates use of the quotation sandwich approach.

Figure 7. A quotation sandwich can contextualize source information for readers

The sandwiching method in shown in Figure 7 can also be used with paraphrases, summaries, visuals, and lists to interweave those elements into a document so it flows together effectively.

Using a quotation from the first page of Charles Dickens’ 1859 novel A Tale of Two Cities —“It was the best of times, it was the worst of times”—textbook writers Last and Neveu (2019, pp. 236-237) explain that the seamless integration, signal phrase, and colon methods can also be used to integrate quotations into a text in a cohesive manner. The following list, adapted from Last and Neveu, explains and exemplifies these methods.

Seamless Integration: Embed the quotation or parts of it into your sentence so that if you read the text aloud, listeners cannot distinguish the quotation from the rest of the sentence.

Example: Charles Dickens begins his 1859 novel with the paradoxical observation that the eighteenth century was both “the best of times” and “the worst of times” (p. 1).

Signal Phrase: Use a signal phrase (author + reporting verb) to introduce the quotation, clearly indicating that the quotation originates from a specific source.

Example: Describing the eighteenth century in his 1859 novel, Charles Dickens observes, “It was the best of times, it was the worst of times” (p. 1). → Notice that a comma follows observes since the verb signals the beginning of a quotation.

Colon: Use a colon to introduce a quotation when your own introductory words constitute an independent clause (i.e., a complete sentence); the colon emphasizes the quotation.

Example: In his 1859 novel, Charles Dickens defines the eighteenth century as a time of paradox: “It was the best of times, it was the worst of times” (p. 1).

Any of these techniques can be used in conjunction with a quotation sandwich for maximum cohesive effect.

Although a quotation extracts the exact words from a source, a writer might need to adjust the quoted material to interleave it into his or her own text so the language flows together in a concise, grammatical manner that makes sense to readers. For example, the writer might need to alter the verb tense of the quotation so it matches the tense used in the rest of the sentence or insert a clarifying comment into the quotation to help readers understand its meaning. Both of these situations call for the use of brackets (i.e., [ ]). Ellipses, three periods in a row (…), are used to show that irrelevant words have been omitted from the middle of a quotation; four periods are used when a sentence or more is omitted from the middle of a quotation. Instead of quoting full sentences, writers oftentimes integrate short phrases or parts of sentences into their texts, using ellipses in these circumstances. If a writer omits words from the beginning or ending of a quotation, the ellipses are unnecessary.

Last and Neveu (2019, p. 238) call upon the following text from Petroski (2014) to demonstrate the use of brackets and ellipses in action. The text is a long quotation (40+ words), so it begins on a new line and is indented rather than enclosed in quotation marks. When citing a long quotation such as this, place the citation information (in this case, the page number of the quotation) outside the final mark of punctuation at the end of the quotation. These are standard conventions for incorporating long quotations into a piece of writing. The examples that accompany the text are adapted from Last and Neveu (2019, p. 238).

Engineers are always striving for success, but failure is seldom far from their minds. In the case of Canadian engineers, this focus on potentially catastrophic flaws in a design is rooted in a failure that occurred over a century ago. In 1907 a bridge of enormous proportions collapsed while still under construction in Quebec. Planners expected that when completed, the 1,800-foot main span of the cantilever bridge would set a world record for long-span bridges of all types, many of which had come to be realized at a great price. According to one superstition, a bridge would claim one life for every million dollars spent on it. In fact, by the time the Quebec Bridge would finally be completed, in 1917, almost ninety construction workers would have been killed in the course of building the $25 million structure. (p. 175)

Petroski, H. (2014). To forgive design: Understanding failure . Belknap Press.

Brackets can be used to signal a change to the verb tense in a quotation:

Petroski (2014) recounts the story of a large bridge that was constructed at the beginning of the twentieth century in Quebec, saying that “by the time [it was done], in 1917, almost ninety construction workers [were] killed in the course of building the $25 million structure” (p. 175).

An ellipsis can be used to signal the omission of words from a quotation:

“Planners expected that when completed, the…bridge would set a world record for long-span bridges of all types,” according to Petroski (2014, p. 175).

Brackets can be used to signal a clarifying insertion into a quotation:

“Planners expected that when completed, the…cantilever bridge [built using structures that were anchored at one end and projected horizontally at the other] would set a world record for long-span bridges of all types,” explained Petroski (2014, p. 175).

Brackets and ellipses help authors cohesively incorporate quotations into their own writing.

When source material contains a misspelling or other composition blunder, signal the error’s presence to readers in a quotation by enclosing the italicized word sic (Latin for thus ) in brackets and placing it right after the error. Here is an example of the notation used in a sentence.

According to Jones’ (2019) Best Journal review, the book is “an important contribution to gender studies, suceeding [ sic ] where others have fallen short” (p. 2).

The notation informs the readers that the mistake appeared in the original text.

Lastly, when quoting text that already contains quotation marks, change the internal double quotation marks (“ ”) to the single variety (‘ ’) to help readers distinguish the elements. Here is an example that illustrates this use of punctuation.

In their journal article “Fish Tales: Combatting Fake Science in Popular Media,” authors Thaler and Shiffman (2015, p. 88) classify “‘bad science’ as unsound conclusions drawn from invalid premises; ‘pseudoscience’ as sound conclusions drawn from invalid premises; and ‘fake science’ as unsound conclusions drawn from invalid premises.”

Help readers understand how you have integrated quotations into your own sentences by using the standard conventions discussed herein.

Using Paraphrases

Paraphrasing is another technique that can be used to integrate evidence from sources into an essay. When paraphrasing , a writer articulates a text’s ideas using his or her own words and sentence structures and cites and references the original source. This technique has a number of benefits, as the following list explains.

To compose a paraphrase, a writer must have a strong command of a source. Thus, inclusion of a paraphrase in an essay demonstrates that a writer has engaged actively with the source and can discuss it in an informed way using his or her own words.
A writer can oftentimes incorporate a paraphrase into an essay in a more straightforward way than a quotation by maintaining his or her own writing style.
If a source uses complex technical terms, a writer can translate this wording for a general audience of essay readers by articulating the ideas in a paraphrase.

Paraphrase when a text’s ideas are more important than how a source communicates them. Also bear in mind that paraphrasing and summarizing are the norm in much academic and technical writing, while quotations are used sparingly if at all.

To be certain you are using your own words and sentence structures when paraphrasing, follow these steps.

Read the source text carefully to make sure you understand it.
Decide which short section of text (a sentence or two or a brief paragraph) you intend to paraphrase.
Note down key points about the text on a separate piece of paper using your own words.
Put the source text away so you cannot see it.
Write your own version of what the original text said using your notes.
Leave the paraphrase alone for a while, and then revisit it to see if it can be improved.
Check that the paraphrase expresses the overall idea of the source text in a new form.
Enclose any unique terms borrowed from the original source in quotation marks.
Provide an in-text citation and accompanying reference list entry for the original text.

The example below, adapted from Last and Neveu (2019, p. 239), follows the principles conveyed in the list while paraphrasing the final two sentences of the Petroski (2014) text presented earlier.

At the end of its construction, the large cantilever bridge in Quebec cost $25 million, explains Petroski (2014, p. 175), but the cost in lives far exceeded the prediction of one death for each million dollars spent. While the planners hoped that the bridge would set a global record, its enduring reputation was much grimmer.

An unacceptable paraphrase is one that simply replaces source language with synonyms. To avoid this form of plagiarism, use the steps listed here to express the meaning of a source in your own words.

Using Summaries

Summarizing , when a writer communicates a text’s central idea or theme in his or her own words while excluding details, is another technique that can be used to integrate source evidence into an essay. Although the “Reading Actively” chapter of this textbook contains detailed summary-writing guidance, Figure 8, a handout adapted from the Robert Gillespie Academic Skills Centre, University of Toronto Mississauga (n.d.), lists essential reminders for constructing a summary.

In what instances might you use summaries in essays?

Figure 8. Steps for composing a summary

The following example, adapted from Last and Neveu (2019, p. 239), follows the principles discussed herein when summarizing the Petroski (2014) text.

According to Petroski (2014, p. 175), a large bridge built in Quebec during the early part of the twentieth century claimed the lives of dozens of workers during its construction. The collapse of the bridge early in its construction represented a pivotal design failure for Canadian engineers that shaped the profession.

As the sample illustrates, a summary condenses an extended text down to its essential meaning, providing readers with an overview; a summary also supplies readers with a citation and reference for the source text.

Synthesizing Ideas for an Essay

Although this chapter has discussed quoting, paraphrasing, and summarizing as means to integrate source information into essays, before you can use these techniques to their fullest potential, you must think carefully about the points your essay sources make, how they concur or disagree with one another, and how they connect to and extend your own ideas about an essay topic. Collectively, these activities facilitate synthesis , or connecting with sources by responding to their ideas and research in a piece of writing in order to contribute your own unique insights to the area of focus. Many composition scholars liken synthesis to engaging in conversation with sources since it involves establishing how sources relate to one another and to your own thoughts about a subject.

Using Summary to Synthesize

To demonstrate synthesis in action, we will explore a scenario adapted from Excelsior Online Writing Lab (2020f). Imagine you are researching a topic. You will likely encounter a variety of sources about the subject that contain different information and points of view, and you will need to compare and evaluate this information to draw your own conclusions—a process that leads to the synthesis of new ideas. It may help, at this point, to compare synthesizing to analyzing. Whereas analysis breaks something into parts to examine how they work together, synthesis combines ideas to form new ones. Regardless, synthesizing is not the same as summarizing; summary involves concisely stating someone else’s ideas, while synthesis is a critical and creative process in which you compare or combine the ideas you have read to form new ones. Although synthesis can involve summarizing ideas from other texts in order to compare them and draw a conclusion, the result is a new idea.

To continue the scenario, we will read two passages that express different points of view about bike lanes: first, we will summarize the authors’ main ideas, and then we will compare them and draw a conclusion. The author of this first passage is in favor of bike lanes.

Bike lanes are an essential feature of modern, urban life. Indeed, many urban residents have traded their cars for bicycles. Bicycling offers many advantages to driving: bicycles do not get stuck in traffic, run out of gas, break down often (and even when they do, repairs are inexpensive), need insurance, produce pollution, or receive parking tickets. They also offer an excellent way to add exercise to a busy schedule. Many cities across the nation have encouraged bicycling to cut down on traffic, accidents, and pollution and have added bike lanes to downtown areas to provide safe and speedy thruways for bicyclists, producing a net positive result for all parties.

We can summarize this argument by pulling out some keywords: bike lanes, advantages, urban, traffic, accidents, pollution, inexpensive, safe, and exercise. Putting this information together, we can summarize the author’s argument as follows.

Placing bike lanes in urban areas is beneficial because bicycling reduces traffic, accidents, and pollution and offers an inexpensive, safe, and healthy way to travel.

The author of the second passage opposes bike lanes, as this text reveals.

Bike lanes remove valuable space from already crowded inner-city streets. Urban areas already suffer from traffic and pedestrian congestion, and such overcrowding is worsened by the introduction of legions of reckless bicyclists. Many bicyclists also ignore street signs, causing additional accidents with cars and people. Furthermore, parked bicycles clutter congested sidewalks, making many areas impassable. These problems far outweigh the benefits of bicycling. People who do not want to drive can hop on a bus or subway and gain most of the benefits of bicycling without taking up precious space on the roads.

We can use several keywords to summarize this argument: bike lanes, urban, space, crowding, accidents, congested sidewalks, problems, buses, and subways. Combining this information leads to the following summary.

Placing bike lanes in urban areas is problematic because bicycles take up valuable space, create additional crowding, cause accidents, and congest sidewalks. Bike lanes can also be replaced with better alternatives, such as buses and subways.

Having summarized the passages, we can practice synthesizing by combining the two summaries and drawing a conclusion.

In the first passage, the author argues that placing bike lanes in urban areas is beneficial because bicycling reduces traffic, accidents, and pollution and offers an inexpensive, safe, and healthy way to travel.
Synthesis: These opposing viewpoints demonstrate that while bike lanes encourage a healthy, safe, and low-cost way to travel in cities, they also cause problems that need to be addressed through better urban planning.

The synthesis statement fuses the two passages by combining and comparing the two summaries and then drawing a conclusion that raises a new idea about the need for better urban planning to support bicycling.

Using a Matrix Tool to Synthesize

When exploring the connections among various sources for an essay, you might also decide to use a matrix tool to create a visual representation of source relationships. When using this type of tool, a writer groups common themes, arguments, or points raised in sources in tabular fashion to facilitate synthesis. Table 2 is an example of a synthesis matrix.

Table 2. A matrix tool to facilitate synthesis

Theme, Argument, or Point 1:

Source 1:

My Thoughts:

Source 2:

Source 3:

Theme, Argument, or Point 2:

Source 1:

My Thoughts:

Source 2:

Source 3:

Theme, Argument, or Point 3:

Source 1:

My Thoughts:

Source 2:

Source 3:

When using a matrix tool, it is vital to consider your own thoughts regarding groupings in order to encourage synthesis, as the right column of the figure indicates.

Signaling Synthesis in an Essay

When synthesizing ideas in an essay, you can help readers understand how they connect by using sentence structures that signal relationships. Bruce and Gagich (2018, p. 93-94) explain that these sentence structures oftentimes point to a writer’s agreement or disagreement with sources, although you can also use them to discuss patterns of thinking, errors in logic, omission of points, or other matters that add to the research conversation. The textbook authors provide examples of sentence structure templates (adapted below) that can be used to establish synthesis.

Source A asserts…Source B agrees when stating…
According to sources A and B…
The combined conclusions of sources A and B seem to indicate that…
The evidence shows that…
Source A is correct that…However, source B’s point that…is also valid.
Source A makes a convincing case when she argues…
I agree with source A’s conclusion that…
Source A asserts that…, while source B offers a different perspective by…
Sources A and B disagree regarding…
Contrary to what source A has argued, my view is that…
I argue that X is the best option even though source B proposes a different solution.
I would like to offer several objections to the opinions expressed by source A…
While source B makes a strong argument, I would disagree with…because…
Instead of focusing on…as source A does, source B emphasizes…
While most of the experts on X see…as the primary cause of…, only source A acknowledges that there may be other…causes.
When I began researching topic X, I expected to find…To my surprise, neither source A, B, nor C address this reason, which leads me to believe that…
Because source A is an expert in the field of X, most others writing about X accede to A’s authority, but a closer examination of A reveals an important omission about X.

These templates demonstrate how you can weave together source information with your own thoughts to create new ideas about a topic.

Although synthesis is critical to developing an effective essay, you will also regularly call upon the skill when producing other types of writing assignments as well.

Formatting an Essay

As with any other type of document you write, design an essay with the principle of consistency in mind so that readers can concentrate on its content rather than on formatting variations. When producing an essay, use double spacing throughout, one-inch margins, and indentation to signal the beginnings of new paragraphs, unless you are told otherwise. This list, adapted from Lambert (2019, paras. 4-8), indicates other ways to stay consistent with design.

Make sure your font and type size is the same throughout the entire paper. If you opt to use different fonts or type sizes for headings and body text, employ this design decision consistently.
Use the same style bullet points throughout lists in the paper. Remember that numbers and letters indicate rank or sequence, whereas bullets do not.
Design lists in a consistent manner. In general, capitalize the first letter of the first word in a list, and use punctuation at the end of full-sentence list items.
Format all same-level headings the same way, using uniform design choices (bold or italic lettering), standardized positioning (center or left alignment), and a consistent pattern of capitalization.
Apply the design principle of repetition when implementing color. If you decide to employ color in visuals, aim to use the same or a similar color in more than one visual.

Keep in mind that certain formatting conventions (e.g., heading design and placement) are associated with documentation styles. The “Reporting Research Outcomes” chapter of this textbook provides specific guidance on formatting documents using APA (American Psychological Association) style.

Developing an Essay Title

An essay’s title offers insight into the accompanying text’s direction, purpose, and content, so devise a precise title that is particular to the paper you are developing and is clearly written with an envisioned audience in mind. Implementing this piece of advice may mean fully drafting the essay before composing its title.

To elaborate on the previous paragraph while adapting advice provided by the Sweetland Center for Writing, University of Michigan (2020b, paras. 5, 11-16), readers typically find titles like “Essay One,” “Society and its Many Problems,” “A Picture is Worth a Thousand Words,” and “Technical Writing Assignment Two” unhelpful. These types of titles are simply too general to provide any needed context. To avoid such titles, think carefully about the essay’s thesis, research, and implications, and identify keywords that succinctly encapsulate these. Imagine, for instance, that you are writing an essay about animal behavior. You have a particular species to study, conduct relevant research, and have conclusions to offer. Here is your first attempt at an essay title: “Monkey Behavior.” This title says nothing about the kind of monkey or its distinctive behavior and does little to attract or inform the reader. Your second attempt is a little better: “The Effects of Sugar on Monkey Behavior.” This title is clearer and somewhat amusing. Regardless, it still does not offer many specifics or include key terms from the paper. Readers can already conjecture that sugar would have some effect on monkey behavior, so the title needs to be markedly more precise. Here is a revised version: “Sugar Stimulates Intensity of Tail-Twitch Social Behavior in Panamanian Monkeys.” This title contains specific terms, includes a clear location, and provides an explicit claim—information the reader can use to immediately identify the paper’s focus.

Developing Essay Headings

Create specific and informative headings for essay sections since headings signal a paper’s organization and scope and help readers follow the text’s development. So, rather than using the vague Body as a heading, divide the body section of the paper into segments organized by the main points covered in paragraphs, which should all relate back to the paper’s thesis statement, and give the sections explanatory headings. By reading an essay’s explanatory headings, the reader should be able to discern the general progression of the piece and what the essay sections cover.

Revising an Essay

Like any quality piece of extended writing, an essay requires time and effort to prepare, and revision is a key step in the composition process. Revision is most effectively completed in stages: a writer begins the process by looking for big-picture issues that might affect an essay’s coherent construction, then considers mid-level issues that can impact paragraph development, and finishes by checking for sentence-level errors that can influence reader understanding. The following list provides guiding questions that can be used during each stage of revision.

Do you have a clear thesis? Do you know what idea or perspective you want the audience to understand upon reading your essay?
Is your essay well organized?
Is each paragraph a building block in your essay: does it explain or support your thesis?
Does the essay need a different shape? Do parts need to be moved?
Do you fully explain and illustrate the main ideas of your paper?
Does your introduction grab the reader’s interest?
Does your conclusion leave the reader with an understanding of your point of view?
What is your paper’s strength? What is its weakness?
Does each paragraph contain solid and specific information, vivid description, or examples that illustrate the point you are making?
Can you add other facts, quotations, paraphrases, examples, or descriptions to more clearly illustrate or provide evidence for the points you are making?
Can you delete any sentences, words, descriptions, or information because they may confuse or tire the reader?
Are your paragraphs in the right order?
Does each paragraph explore one main idea?
Do you use clear transitions so the reader can follow your thinking?
Do any of your paragraphs contain redundancies that can be deleted?
Have you been consistent in your use of tense?
Do your pronouns agree with their antecedents (referents)?
Have you accurately and effectively used punctuation?
Do you rely on strong verbs and nouns to enhance descriptions and build clear sentences?
Are your words as accurate as possible?
Do you define any technical or unusual terms that readers may not know?
Can you delete any extra words from your sentences?
Have you avoided clichés and slang?
Do you vary your sentence structures?
Have you accurately presented facts?
If you are writing an academic essay, have you tried to be objective in your evidence and tone?
If you are writing a personal essay, have you used a lively narrative voice?
Have you spellchecked your paper?
Have you ethically incorporated source material by effectively quoting, paraphrasing, or summarizing it?
Have you consistently cited and referenced source information using a standard documentation style?

Although a draft paper represents an important milestone in a writing project, a draft typically needs considerable revision and refinement before it is ready for submission. Figure 9, an essay extract reproduced courtesy of Excelsior Online Writing Lab (2020d, “Rough Draft Example”), illustrates this point.

Figure 9. The revising process at work in an essay extract

Think of revising as a recursive activity, meaning that you may proceed through the previously listed revision stages multiple times during an essay’s development.

In addition to revising a paper in stages using the prompt questions listed, you may also have the opportunity to revise an essay based on peer feedback. Peer review sessions offer valuable chances to find out what others think of your writing and what suggestions they can contribute to help you during revision; the sessions also give you the chance to supply constructive feedback on your classmates’ writing—a vital skill you will need in the workplace. When supplying constructive criticism, identify what needs to be changed in a paper, why it needs to be changed, and how it can be changed. Alternatively, highlight what works well in a paper, why this is the case, and how the positive aspect affects you, the reader. Figure 10, a multipage handout produced by the Writing and Communication Centre, University of Waterloo (n.d.b), offers further peer review advice and a feedback template that can be used during peer review sessions to help ensure they are maximally productive.

Have you ever participated in a peer revision session before? What did you think of it? What do you think of the peer review advice presented in the handout?

Peer Review Theory and Practice

Peer review is one of a number of revision and proofreading strategies available to you. While there are many ways to structure peer review sessions, at its core, this technique involves soliciting feedback on one or more aspects of your writing from classmates or colleagues.

Peer Review: Purpose and Scope

interact, models, concrete advice, and think and learn

While peer review has the obvious benefit of getting feedback on your writing, it also has benefits for the person doing the reviewing:

We become better writers by being diligent peer reviewers
We learn good writing habits by writing often and by reading the writing of others
Giving feedback requires us to think carefully – not only about what we think about someone’s writing, but also about how writing is constructed and why we are making specific suggestions.

It is up to individual peer review groups to determine what aspects of writing a given session (or series of sessions) will look at. Broadly speaking, the following aspects of writing are the ones that you could potentially focus on:

Content : arguments, analysis, logic, evidence
Structure : organization, transitions, connections
Style : tone, word choice, formality
Mechanics : punctuation, sentence structure, spelling

General Tip :Avoid the urge to focus initially or primarily on mechanics. The revision and proofreading process will be more effective when you focus on higher-order concerns (content and structure) first and lower-order concerns (style and mechanics) second. See our handouts on revision and proofreading for more strategies that you can use.

Done correctly, the peer review process is a social, productive, and engaging way of participating in your discipline’s community of practice. However, though some instructors or supervisors will encourage their students to work together in a peer review process, others may require that projects be completed independently. In order to avoid any issues around academic integrity , make sure to consult with your instructor or supervisor before engaging in peer review.

Peer Review: Spaces

There are lots of spaces available for conducting peer review, including the following:

Face-to-Face

Coffee shop
Someone’s home
Google Hangouts
Google Docs

Peer Review: Practice

Steps in peer review.

explain what to look for, exchange, feedback for improvement, and discuss and plan

Write notes for your reviewer on the peer review sheet and exchange papers. If you are not using a peer review sheet, discuss the specific questions or concerns that you’d like your reviewer to pay attention to.
Read actively and critically . Make notes in the margins of the paper or in the track changes feature if using Word. If using a review sheet, make general notes there, too.
Return the paper (and the review sheet, if you used one) to the original writer; discuss the feedback and create an action plan for revision and proofreading.

Sample Peer Review Worksheet

Feel free to adapt the templates of these peer review worksheets to suit your needs Printable version of Peer Review Worksheet (PDF) Fillable Peer Review Marking form (PDF)

Peer Review Marking Sheet

Name of Writer:

Name of Reviewer:

Notes from the writer to the reviewer:

Aspect of Writing Being Reviewed: Content / Structure / Style / Mechanics


( )
( )
(e.g., Use of transition words or phrases)

Additional comments on writing :

Post-Review Discussion

Action Plan: How will you (the writer) incorporate the suggestions of your reviewer into your edits? What steps will you take during the editing process? Be specific:

Figure 10. Peer review guidance and a feedback template

Notice that the final procedure on the handout asks you to specify how you will use peer comments to revise your paper, a crucial step when working with feedback.

Drawing the Chapter to a Close

Take the advice in this chapter into account when preparing an essay to persuasively communicate with readers.

Activity A: Producing a Reverse Outline and Answering Questions about an Essay

This chapter discusses revising in stages and peer reviewing as means to facilitate the revision process. A reverse outline offers another technique that can be used to revise an essay, as the following handout, adapted from Student Academic Success Services, Queen’s University (2018c), describes.

Reverse Outline

Practice using the reverse outline technique with the sample proposal essay provided on upcoming pages (Hanna, 2020, as cited in Excelsior Online Writing Lab, 2020e, “Sample Essay”). The essay argues for streamlining the recycling infrastructure on a college campus to encourage recycling.

Sample Essay

After reading the proposal essay, also answer the following questions about it. Be prepared to share your answers in class.

In what way does the author create a narrowly defined focus for the essay?
Does the author provide sufficient coverage of her topic in the paper? How?
Identify the introduction, body, and conclusion sections of the essay. Are they logically structured and easy to follow? What makes them so?
A proposal aims to persuade readers. What does the author do to try to persuade you in her essay?
What do you think about the evidence the writer uses? For instance, is it accurate, trustworthy, relevant, sufficient, and timely?
How does the writer incorporate source evidence into the essay? Could her technique be improved in any way? If so, how?
Where do you detect synthesis in the essay?
What do you think of the essay’s formatting? Could it be improved in some way?
Do you think the writer has put sufficient effort into revision? What makes you think so?
Imagine you are giving constructive criticism to the author during a peer review session. Identify one thing that needs to be changed in the paper, why it needs to be changed, and how it can be changed. In addition, name one thing that works well in the paper, why this is the case, and how the positive aspect affects you, the reader.

Activity B: Reading and Answering Questions about an Essay Focused on Source Credibility

Read Warrington et al.’s (2020) essay entitled “Assessing Source Credibility for Crafting a Well-Informed Argument” located at https://wac.colostate.edu/docs/books/writingspaces3/warrington.pdf . To reflect on the essay and its relevance to your own academic work, answer the five questions starting on page 202 of the text. Be prepared to talk about your answers in class.

Activity C: Applying the Ideas Discussed in the Essay to a Text

Working with a group of classmates, apply the credibility questions Warrington et al. discuss in their essay to the journal article “Fish Tales: Combatting Fake Science in Popular Media” (Thaler & Shiffman, 2015), which is available at https://www.sciencedirect.com/science/article/pii/S0964569115000903 . Afterwards, share your group’s determination about the article’s credibility with the whole class during a brief informal presentation. This activity is adapted from Warrington et al. (2020, p. 203).

Academic Writing Help Centre, Student Academic Success Service, University of Ottawa. (2016a). Body . License: CC-BY 4.0 . https://sass.uottawa.ca/sites/sass.uottawa.ca/files/awhc-body.pdf

Academic Writing Help Centre, Student Academic Success Service, University of Ottawa. (2016b). Conclusion . License: CC-BY 4.0 . https://sass.uottawa.ca/sites/sass.uottawa.ca/files/awhc-conclusion.pdf

Academic Writing Help Centre, Student Academic Success Service, University of Ottawa. (2016c). Introduction . License: CC-BY 4.0 . https://sass.uottawa.ca/sites/sass.uottawa.ca/files/awhc-introduction.pdf

Bruce, Y., & Gagich, M. (2018). Synthesizing in your writing . In M. Gagich, E. Zickel, A. Lloyd, C. Morgan, J. Lanning, R. Mustafa, S.M. Lacy, W. Breeze, & Y. Bruce , In practice: A guide to rhetoric, genre, and success in first-year writing (pp. 93-94). MSL Academic Endeavors. License: CC-BY-NC-SA 4.0. https://pressbooks.ulib.csuohio.edu/csu-fyw-rhetoric/

Excelsior Online Writing Lab. (2020a). Revising stage 1: Seeing the big picture . License: CC-BY 4.0 . https://owl.excelsior.edu/writing-process/revising-and-editing/revising-and-editing-revising-stage-1/

Excelsior Online Writing Lab. (2020b). Revising stage 2: Mid-view . License: CC-BY 4.0 . https://owl.excelsior.edu/writing-process/revising-and-editing/revising-and-editing-revising-stage-2/

Excelsior Online Writing Lab. (2020c). Revising stage 3: Editing up close . License: CC-BY 4.0 . https://owl.excelsior.edu/writing-process/revising-and-editing/revising-and-editing-revising-stage-3/

Excelsior Online Writing Lab. (2020d). Rough drafts . License: CC-BY 4.0 . https://owl.excelsior.edu/writing-process/essay-writing/essay-writing-rough-drafts/

Excelsior Online Writing Lab. (2020e). Sample proposal assignment . License: CC-BY 4.0 . https://owl.excelsior.edu/argument-and-critical-thinking/argumentative-purposes/argumentative-purposes-sample-proposal-argument/

Excelsior Online Writing Lab. (2020f). Synthesizing what you read [Video transcript]. License: CC-BY 4.0. https://owl.excelsior.edu/wp-content/uploads/sites/2/2017/02/SynthesizingTranscript2019.pdf

George Mason University Writing Center. (2017). Reducing informality in academic writing . https://writingcenter.gmu.edu/guides/reducing-informality-in-academic-writing

Lambert, R. (2019). Writing with consistency . Colorado School of Mines Writing Center. License: CC-BY-NC 4.0 . https://www.mines.edu/otcc/wp-content/uploads/sites/303/2019/12/OTCCConsistencyLesson.pdf

Last, S., & Neveu, C. (2019). Appendix C: Integrating source evidence into your writing. In S. Last, Technical writing essentials: Introduction to professional communications in the technical fields (pp. 235-242). University of Victoria. License: CC-BY 4.0 . https://pressbooks.bccampus.ca/technicalwriting/

McKeever, R. (n.d.a). Post-truth: Evaluating sources . Yuba College Writing and Language Development Center. License: CC-BY-NC 4.0. https://yc.yccd.edu/wp-content/uploads/2019/03/EvalSourcesPostTruthAccessibleMarch2019.pdf

McKeever, R. (n.d.b). The quote “sandwich.” Yuba College Writing and Language Development Center. License: CC-BY-NC 4.0. https://yc.yccd.edu/wp-content/uploads/2017/05/QuoteSandwich.pdf

McKeever, R. (n.d.c). Thesis statements . Yuba College Writing and Language Development Center. License: CC-BY-NC 4.0. https://yc.yccd.edu/wp-content/uploads/2020/02/ThesisStatementAccessibleFebruary2020.pdf

Robert Gillespie Academic Skills Centre, University of Toronto Mississauga. (n.d.). Six effective tips to write a summary . License: CC-BY-NC-SA 4.0 . https://www.utm.utoronto.ca/asc/sites/files/asc/public/shared/pdf/tip_sheets_writing/Summary_6Tips_web_v1.pdf

Schall, J. (2014). Essays and term papers: Effective technical writing in the information age . Penn State College of Earth and Mineral Sciences. License: CC-BY-NC-SA 3.0 . https://www.e-education.psu.edu/styleforstudents/c6_p13.html

Student Academic Success Services, Queen’s University. (2018a). Developing the “what”: Effective topic sentences . License: CC-BY-NC-SA 2.5 . https://sass.queensu.ca/wp-content/uploads/2019/04/Developing-a-Topic-Sentence.pdf

Student Academic Success Services, Queen’s University. (2018b). Organizing the body of an essay . License: CC-BY-NC-SA 2.5 . https://sass.queensu.ca/wp-content/uploads/2019/04/Process-Essay-Body-Organization.pdf

Student Academic Success Services, Queen’s University. (2018c). The reverse outline . License: CC-BY-NC-SA 2.5 . https://sass.queensu.ca/wp-content/uploads/2019/04/The-Reverse-Outline.pdf

Sweetland Center for Writing, University of Michigan. (2020a). How can I create a strong thesis . License: CC-BY-NC-SA. https://lsa.umich.edu/sweetland/undergraduates/writing-guides/how-can-i-create-a-stronger-thesis.html

Sweetland Center for Writing, University of Michigan. (2020b). How do I write a great title for my academic essay? License: CC-BY-NC-SA. https://lsa.umich.edu/sweetland/undergraduates/writing-guides/how-do-i-write-a-great-title-.html

Thaler, A.D., & Shiffman, D. (2015). Fish tales: Combating fake science in popular media. Ocean & Coastal Management, 115 , 88-91. https://doi.org/10.1016/j.ocecoaman.2015.04.005

Warrington, K., Kovalyova, N., & King, C. (2020). Assessing source credibility for crafting a well-informed argument. In D. Driscoll, M. Stewart, & M. Vetter (Eds.), Writing spaces: Readings on writing (Vol. 3, pp. 189-203). Parlor Press. License: CC-BY-NC-ND 4.0 . https://wac.colostate.edu/docs/books/writingspaces3/warrington.pdf

Webber, N.R. (2018). Activity: Source evaluation scorecard. Information Literacy, 19 . License: CC-BY 4.0 . https://digscholarship.unco.edu/cgi/viewcontent.cgi?article=1018&context=infolit

Writing and Communication Centre, University of Waterloo. (n.d.a). Develop and narrow a topic . License: CC-BY-SA 4.0 . https://uwaterloo.ca/writing-and-communication-centre/sites/ca.writing-and-communication-centre/files/uploads/files/narrow_your_topic.pdf

Writing and Communication Centre, University of Waterloo. (n.d.b). Peer review: Theory and practice . License: CC-BY-SA 4.0 . https://uwaterloo.ca/writing-and-communication-centre/sites/ca.writing-and-communication-centre/files/uploads/files/peer_review.pdf

Writing and Communication Centre, University of Waterloo. (n.d.c). Thesis statements . License: CC-BY-SA 4.0 . https://uwaterloo.ca/writing-and-communication-centre/sites/ca.writing-and-communication-centre/files/uploads/files/thesis_statements.pdf

Share This Book

Experiences
Suggestion Box
Review Sites
Professional Persona

Technical essay style guide

This class will provide you with many opportunities to practice the art of technical essay writing. Here are some simple guidelines you can use to avoid common problems.

1. Name the essay file according to its subject (not its date).

The techfolio template essay files are named with the date they were created (i.e 2015-08-26.md). Don’t do this: name each essay file to reflect its subject matter. For example, you might base the file name on the title of your essay. If your essay title is “Igniting the fire”, then your file name might be “igniting-the-fire.md”.

Do not include spaces in the file name: use “igniting-the-fire.md”, not “igniting the fire.md”.

If the browser is downloading the file instead of displaying it, that’s probably because the file name does not end with “.md”.

Correct naming is important so that the URL associated with your essay is easy to read and provides an indication of its subject matter.

Don’t ever use “reflect” or “reflections” as part of your file name.

2. Create an interesting title that draws in the reader.

Do not name your essay with the module name (i.e. “Configuration Management”) or the experience name (i.e. “Reflections on Javascript”). Search engines often emphasize the title of pages. Would you want to read an essay based on a title like that? I sure wouldn’t. With a little bit of thought, you can come up with something personal (i.e. “The configuration management catastrophe that almost cost me my job”) or clever (“You can’t always git what you want”).

Don’t ever use “reflect” or “reflections” as part of your title.

3. Use appropriate spelling and grammar

Don’t misspell words. Use appropriate grammar. If you are not confident, avail yourself of online tools to check spelling and grammar prior to publication.

4. Write for the world, not the professor

Although many of your essays will be based upon your experiences doing home assignments (i.e. experiences), do not write your essay as it if were a private email to the professor explaining the assignment. Don’t create sections to answer each of the “questions” from the prompt. If you do that, you’ll almost certainly create a boring essay that is not interesting to read.

Instead, write it “for the world”. Assume some random technical professional has been googling and your essay came up. Make the essay self-contained, self-explanatory, and useful to that random professional. Minimize the assumptions you make about that person’s software engineering background (much less their background in this class!) Provide links to background material if useful.

Not only should you write it for a variety of people, you should write it for a variety of times. In other words, try to write your essay such that if someone reads it in a year, it will still provide information of value. If you’re a newbie to the subject, then write it to provide insight and understanding to other newbies.

To make an essay compelling, it is usually helpful to “tell a story”. Create a narrative, don’t just answer questions.

5. Format code appropriately

Make sure that code displays properly in your posting. You accomplish this by using fenced code blocks and syntax highlighting . Here’s an example of javascript code highlighting :

Think carefully before including large code snippets (beyond, say 50 lines). As a rule of thumb, keep code snippets to a reasonable length and make sure all of the code is directly related to the subject of your essay.

6. Use internal headings to structure your essay

Good essays have some sort of internal structure. Help the reader understand this structure by providing internal headings. Don’t start with H1 (i.e. # in Markdown), as that’s reserved for the title of your post. Instead, start with H2 ( ## in markdown), then create subsections within that section with H3 ( ### in markdown), etc.

Similarly, use itemized or enumerated lists, tables, etc as appropriate.

7. Format and attribute quotations

You will occasionally want to quote another writer in your technical essays. This is fine as long as you do not present those words as your own.

If you are just quoting a single sentence or two, you can simply use italics, quotation marks, and provide the author’s name. For example:

As noted by Steve Jobs, “Design is not just what it looks like and feels like. Design is how it works.”

For longer quotes, use the <blockquote> environment along with <footer>. For example:

A cynical young person is almost the saddest sight to see, because it means that he or she has gone from knowing nothing to believing nothing. Maya Angelou

8. Include pictures or other media

As they say, “A picture is worth a thousand words.” It is very easy to include pictures and videos in your essays. If the meaning of your essay will be communicated more clearly with images, take the time to find and include them. See the Formatting section of the TechFolio User Guide for instructions on how to include images and video.

9. Don’t be boring, don’t be inappropriate

Just because the essay is technical in nature, it doesn’t have to be boring. Try to inject your personality into your writing. You can have “clever” titles, pop culture references, and so forth.

On the other hand, don’t go overboard on the cleverness. Ask yourself: would I be embarrassed if my mother read this essay? (Because she might.) Would I be embarrassed if a potential employer read this essay? (Because she might.)

The goal is to be creative, to show some personality, and to make the essay fun to read as well as informative.

10. Don’t write it at the last minute

The quality of your essays will rise substantially if you develop them as follows:

Write the first draft.
Do something else for 4 hours.
Come back and do an editing pass over the first draft.

The editing pass will normally catch a lot of problems and allow you to refine your thoughts significantly, as long as you’ve stepped away from the essay for a sufficient amount of time to allow yourself to see it with “fresh eyes”. The best way to do that is to sleep on it overnight, but if you don’t have that much time, then at least do something different for a few hours. This lets your subconscious go to work on the material.

11. Review your post’s content and appearance

Once you’ve written and published it, retrieve it in a browser and see how it looks.

12. One paragraph is not enough

Writing a two or three sentence essay in hopes of getting some partial credit is not a good strategy. For one thing, such an essay reflects more poorly on your professional persona than no essay at all. For another thing, we tend to award zero points for essays that reflect very little effort.

13. Make use of the UH Manoa Writing Center

The UHM Writing Center provides consultants who are trained to help at all stages of the writing process; whether you are just getting started, revising a draft, or at some point in between.

You can schedule up to two appointments per week as well as three walk-in appointments per week.

Writing Technical Instructions

Resources & Preparation
Instructional Plan
Related Resources

Learning to write technical instructions is challenging. Writers must consider audience, purpose, context, length, and complexity—plus the specific content of the instructions, such as the steps in using a stapler. In this lesson, students walk through the process of creating technical instructions by first analyzing existing instructions. They then select an item and an audience for which they will write technical instructions. After writing their own instructions, students conduct usability tests of each other's instructions, providing user feedback. Finally, students use this user feedback to revise their instructions before publishing them.

Featured Resources

Analyzing Technical Instructions : Students can use the questions on this handout as a guide when they analyze sample technical instructions. Technical Instructions Planning Sheet : This handout explains the process for working with a partner to plan the technical instructions they will write. Conducting a Usability Test : This handout includes instructions for testing the technical instructions students have written.

From Theory to Practice

Teaching students how to write technical instructions helps them see that "to write, to engage in any communication, is to participate in a community; to write well is to understand the conditions of one's own participation-the concepts, values, traditions, and style which permit identification with that community and determine the success or failure of communication" (Miller 22). Similarly, in discussing finding meaningful writing activities for the English classroom, Weber writes: "The technical writing approach is one of many avenues to this goal. It engages my students in the total communications process: creating, planning, writing, editing, presenting, listening, sharing, and evaluating." Understanding discourse communities requires students to analyze the audience for a written work, and learning to write instructions is one such way students can learn about both audience analysis and technical writing. This lesson works toward building students' understanding of the importance their writing has on real audiences. Further Reading

Common Core Standards

This resource has been aligned to the Common Core State Standards for states in which they have been adopted. If a state does not appear in the drop-down, CCSS alignments are forthcoming.

State Standards

This lesson has been aligned to standards in the following states. If a state does not appear in the drop-down, standard alignments are not currently available for that state.

NCTE/IRA National Standards for the English Language Arts

1. Students read a wide range of print and nonprint texts to build an understanding of texts, of themselves, and of the cultures of the United States and the world; to acquire new information; to respond to the needs and demands of society and the workplace; and for personal fulfillment. Among these texts are fiction and nonfiction, classic and contemporary works.
4. Students adjust their use of spoken, written, and visual language (e.g., conventions, style, vocabulary) to communicate effectively with a variety of audiences and for different purposes.
5. Students employ a wide range of strategies as they write and use different writing process elements appropriately to communicate with different audiences for a variety of purposes.
6. Students apply knowledge of language structure, language conventions (e.g., spelling and punctuation), media techniques, figurative language, and genre to create, critique, and discuss print and nonprint texts.
8. Students use a variety of technological and information resources (e.g., libraries, databases, computer networks, video) to gather and synthesize information and to create and communicate knowledge.
9. Students develop an understanding of and respect for diversity in language use, patterns, and dialects across cultures, ethnic groups, geographic regions, and social roles.
11. Students participate as knowledgeable, reflective, creative, and critical members of a variety of literacy communities.
12. Students use spoken, written, and visual language to accomplish their own purposes (e.g., for learning, enjoyment, persuasion, and the exchange of information).

Materials and Technology

Sample technical instructions (Manuals, user guides, etc.)
Household items for writing instructions
Access to computer with Internet connection, Microsoft Word or Publisher, and printer
Large white paper (Chart-sized sticky notes work well for hanging items on wall)
Digital camera (optional)
Analyzing Technical Instructions
Sample Technical Instructions Rubric
Technical Instructions Planning Sheet
Visually Drafting Your Instructions
Using ReadWriteThink Notetaker to Draft Instructions
Conducting a Usability Test

Preparation

Collect a variety of written technical instructions for household items for students to use to analyze. Try to collect both effective and ineffective examples. Examples are also available online, at the Websites listed in the Resources section . Review the examples to familiarize yourself with their features and effectiveness.
Prepare three or four examples of effective and ineffective written technical instructions, using those you gathered or online examples, to be shown on an overhead or a document camera.
Make sure students have access to computer labs during sessions two through five.
Prepare copies of all handouts for distribution in class.
Test the Notetaker on your computers to familiarize yourself with the tool and ensure that you have the Flash plug-in installed. You can download the plug-in from the technical support page.

Student Objectives

Students will

analyze technical instructions to learn what makes them effective or ineffective for an audience.
analyze and describe the audience for a set of instructions, noting what that audience needs from that document.
understand the difference between technical writing and other genres of writing.
use document and audience analysis, drafting, peer response/user feedback, and revision to create effective technical instructions.
reflect on their writing process, noting how this assignment will be useful to them in future writing.

Session One

Ask students to talk about their experiences reading and using different types of written texts.
How are these different?
How do these genres speak to different audiences?
How do these types of writing work toward different purposes?
Ask students to focus on technical writing as a genre and to brainstorm the different kinds of written instructions they have seen or used in the past. Record their responses on the board or an overhead transparency.
What were they using the instructions for?
How helpful were they?
What were the best parts of the instructions?
What parts were difficult or hard to use?
What did they do if they had trouble using the instructions?
Arrange the class in groups of two to four students each, and give each group a set of instructions from those that you gathered. If the class meets in a computer classroom, share the links to instructions included in the Resources section.
Pass out copies of the Analyzing Technical Instructions , and ask students to analyze their instructions and record their observations on the handout.
When students complete their analysis, bring the class together and have each group report on their set of instructions.
On a sheet of chart paper, make a list of the top five effective and top five ineffective things students noticed about the instructions.
Hang this paper on the wall in the classroom for reference during the next three class sessions.
Ask students to bring one common household item to the next class session. Explain that students will write their own instructions for the item, so they should bring items that do not already have written instructions.
Brainstorm and discuss with students what would make good items and what would be too complex.
Encourage them to bring items that are not overly complex but not too simple either. Examples may include a stapler, clock, paper punch, flashlight, mechanical pencil, etc. Students should be able to write instructions for operating 2–3 features of the item. (For example, how to use a stapler and how to replace staples when cartridge is empty.) Encourage students to be creative in their choices.
Gather some extra items from the classroom or your home before the next session so you have options for students who forget to bring items.

Session Two

Review the top five effective and ineffective things about technical instructions from previous session with the class.
Spend more time with this topic, asking students to create a rubric determining what makes technical documents effective or ineffective. Use the Sample Technical Instructions Rubric as a model or starting point for the task.
Ask students to take out their household item, and spend five minutes freewriting about why they chose that item and how difficult it may or may not be to write instructions for it.
Arrange students in pairs, and ask them to share the item they brought and their thoughts from the freewriting.
Have students interview each other, using the Technical Instructions Planning Sheet to take notes about each other’s items.
Once interviews are complete, have students begin drafting their instructions. Give them large pieces of white paper for them to design, or mock up, their rough drafts.
Pass out copies or share an overhead transparency of the Visually Drafting Your Instructions sheet. Explain that students will draw separate boxes for each part of the item they want their instructions to cover, following the information on the handout.
Demonstrate how to use the ReadWriteThink Notetaker to document the steps in instructions, sharing the Using ReadWriteThink Notetaker to Draft Instructions handout with the class.
Have students use their notes on the Planning Sheet and their copies of the Visually Drafting Your Instructions handout to begin writing. Students can use the Notetaker to draft their instructions.
After students have outlined their instructions using Notetaker , ask them to print their work. Work cannot be saved in the Notetaker .
For homework, ask students to continue drafting their outlines using the Notetaker . Students should bring printed copies of Notetaker outlines to next session.

Session Three

Review outlines created using ReadWriteThink Notetaker with students.
Ask students to discuss how they will organize their notes into instructions, how many pages they will need, whether they need to include pictures to illustrate instructions.
The Process of Writing a Technical Manual
Instructions: How to Write for Busy, Grouchy People
After students review the site, ask them to write down three things they learned that they will consider as they write their own instructions.
Invite students to share their observations and discuss the advice as a whole class.
Review the expectations for the project using the rubric students created during the previous session. Answer any questions that students have about the project.
Explain the options that students have for creating polished drafts of their work. Point out the available software (e.g., Microsoft Word, Publisher) that students can use to type and format their instructions. (Depending on the class, instructors may need to instruct students on using the software to do this).
inserting Clip Art images.
drawing diagrams of their items using the computer or drawing by hand.
labeling parts or connecting the diagrams to the instructions.
importing images taken with a digital camera.
Ask students to print copies of their instructions when finished.
If additional time is needed, ask students to finish drafting their instructions for homework.
Remind students to bring a copy of their instructions and the related item to the next class.

Session Four

Students will bring a copy of their printed (complete) instructions and their household item.
Pass out copies of the instructions for Conducting a Usability Test and review the instructions with students.
Ask students to use the remaining class time to conduct at least two usability tests. Ensure that students understand that two different students will read and test their instructions for using the household item.
If time allows, students can begin revising their instructions in class and consult with the testers as appropriate.
For homework, students can continue working on revising their instructions. Students will finish revisions during the next session and submit their work.

Session Five

Have students revise their instructions, using the available resources—word processing software, clip art, and so forth.
Encourage students to consult the notes from their usability testing as they revise.
As students revise, circulate through the room, meeting with student to discuss revisions and offer suggestions.
Ask students to print their technical instructions, staple or attach pages as needed, and present final products to the class or school by the end of the session.
Spend additional time exploring document design by exploring alternative publishing options such as pamphlets, brochures, and different-sized documents.
Rather than writing instructions for operating a common household item, ask students to write instructions for completing a basic task, such as making a sandwich or addressing an envelope.
For a humorous break, share this Wendy’s training video and ask students to discuss what was effective and ineffective about those instructions. Be sure to discuss when the video was produced and how the video fit (or didn’t) the needs of the audience at the time it was produced.

Student Assessment / Reflections

Collect students’ worksheets, including the Analyzing Technical Instructions and the Technical Instructions Planning Sheet , and the notes taken during the Usability Test . Review the work for completion and understanding of the basic goals of the lesson, including comprehension of the role that audience and purpose play in effective technical writing.
During class discussion and students’ work in pairs, listen for comments that show students can think critically about the goals and effective strategies for technical writing in general and specifically for instructions.
For a formal assessment, use the rubric created by the class during Session Two, which was based on the the Sample Technical Instructions Rubric .
Student Interactives
Lesson Plans

Useful for a wide variety of reading and writing activities, this outlining tool allows students to organize up to five levels of information.

Print this resource

Explore Resources by Grade

Kindergarten K

Technical Writing Examples for Students - Learn How to Write Technically & Clearly

Trent Lorcher
Categories : Help with writing assignments paragraphs, essays, outlines & more
Tags : Homework help & study guides

Technically, That’s not Technical

Extract the metallic pin in the like manner Odysseus extracted the Wooden Horse plan from his mind.
Think of the fire as a tree that you really need to chop down and the extinguisher as your ax. Aim accordingly.
Much like a tender chicken must be roasted slowly, so must the fire extinguisher lever be pressed.
Sweep the extinguisher from side to side much in the same way Emily Dickinson uses her many-colored broom .

Thanks for teaching me all these literary devices. I hope you find them as useful as I have. As I ran out of the burning building, I realized I should have focused a little more on technical writing.

Technically, This Is Technical (Writing)

Technical writing is a type of writing that helps someone solve a problem or acquire necessary information about a specific subject. Examples of technical writing include instruction manuals, recipes, how-to guides, text books, multimedia presentations, and operating instructions. Every occupation and field of study has its own language that’s incorporated into specialized reports and other written work. This, too, is considered technical writing. The following is an example on how to write technically:

Know your audience - This is true for all types of writing. You must know to whom you are writing. If you’re writing, for example, an instruction manual on how to program a cell phone for the general public, you’re going to use words that most people will understand. If you’re writing the same manual for a group of software designers for Verizon Wireless, you’re going to use more technical terms and more complex functions.
Write an introduction - Keep the introduction short. Let the reader know who needs to read it and why they need to read it. If the reader belongs to the “who” group and your “why” solves his problem, then you have just grabbed his attention. (See the introduction to this how-to-example.)
Be direct - Readers of technical writing are not looking for a life-changing literary experience. They have a problem. They want you to solve it. If it’s an instruction or how-to manual, use the imperative voice. If it’s a technical analysis or a report for the boss, leave out any unnecessary words .
Use space - If this example was one long paragraph instead of a numbered list, you would have clicked off it immediately. Brains like order and space. Small paragraphs are good. Numbered or bulleted lists are great. If a specific order is required, use numbers; otherwise, use bullets.
Try it before you submit it . It’s a good idea to test your technical writing, especially if it involves instructions. You can also have a friend try it. The directions must be clear enough for someone else to follow. Your tester/guinea pig/editor may point out ambiguous instructions or unclear explanations that you may not have discovered.

Technically, These Are Great Examples

Here are some technical writing examples for students to get started practicing.

Write two instruction manuals on how to use Facebook, Twitter, or any of those other social media things high school kids are so good at. Write the first manual for people like your Uncle Ned who goes to his mailbox to check his e-mail. Write the second manual for your peers.

Take a multi-step assignment from one of your classes and rewrite the instructions. Make the instructions step-by-step. Show the newly written instructions to your teacher and make sure you captured the essence of the assignment. He or she may want a copy of them. Ask for money in return.

Write a contract regarding chores around your house. Be sure to define all terms. Be specific in what you will do and what is required of the head of household. If you can get your parents to sign the contract, watch out. They probably found a loophole.

Using your class schedule, write a course catalog. Another option is to write a survival guide for a class you are taking. Use humor, if you’ve got it.

Rewrite a school policy.

Write an annual report on your accomplishments during the current school year. Be sure to provide data.

Write specific instructions on how to complete an ordinary task.

Write a recipe. This is harder than it seems. The directions must be specific enough for someone to make the food properly.

These are just a few technical writing examples for students that would make for a great assignment. I hoped they have helped you think of other possibilities as well.

Jerz, Dennis G. “ Instructions: How to Write for Busy, Grouchy People .” Setonhill.edu. 10 November 2002. Accessed 25 May 2011.
Image by Wokandapix from Pixabay

This post is part of the series: Writing Made Easy

Writing isn’t as hard as you think.

How to Make an Outline: Components of the Writing Process
How to Write in the Active Voice & When to Write in Passive Voice
Getting Technical With Technical Writing
Analyze This: Write a Chapter Analysis that Will Amaze Your Teacher

COMMENTS

A Guide to Technical Writing (With Examples)
What Is Technical Writing? Technical writing doesn't always look very technical! It can be anything that describes how to do a task or how to operate a machine or system. Or it can cover a specialized topic. Technical writing includes recipes in your favorite cookbook, board game instructions, operator manuals, health and safety regulations, legal documents, and financial reports.
33 Good Technical Writing Examples (Word & PDF)
33 Good Technical Writing Examples (Word & PDF) The advancement in technology inevitably leads to people training their skills in technical writing, a valuable asset. The skill is crucial, especially for those who work in tech-related businesses. Learning how to make technical writing examples gives you the ability to communicate knowledge.
7.7 Writing Instructions
7. COMMON DOCUMENT TYPES. One of the most common and important uses of technical writing is to provide instructions, those step-by-step explanations of how to assemble, operate, repair, or do routine maintenance on something. Although they may seems intuitive and simple to write, instructions are some of the worst-written documents you can find.
11 Technical Writing Examples & Samples in 2024
Are you beginning your journey as a technical writer? Explore this post to discover commonly used technical writing examples.
What is Technical Writing? A Comprehensive Overview
Technical writing is different from other forms of writing. While other forms of writing may aim to entertain, inspire, or express opinions to readers, technical writing focuses on instructing. It targets specific audiences with varying levels of technical knowledge and uses clear, concise, and objective language.
Writing Instructions
Writing Instructions. One of the most common and important uses of technical writing is instructions—those step-by-step explanations of how to do things: assemble something, operate something, repair something, or explain a personal process (enrolling in college, for example) so that readers may better understand it and possibly use it ...
8 Technical Writing Examples to Inspire You
There are many examples of technical writing, such as preparing instruction manuals and writing complete guides. In some cases, technical writing includes preparing research journals, writing support documents, and other technical documentation. The idea is to help the final user understand any technical aspects of the product or service.
Technical Writing for Beginners
Technical writing is the art of providing detail-oriented instruction to help users understand a specific skill or product. And a technical writer is someone who writes these instructions, otherwise known as technical documentation or tutorials. This could include user manuals, online support articles, or internal docs for coders/API developers ...
Instructions
Instructions. Instructions—those step-by-step explanations of how to build, operate, repair, or maintain things—are one of the most common and important types of technical writing. However, for something seemingly so easy and intuitive, instructions are some of the worst-written documents you can find. You've probably had many infuriating ...
Chapter 8: Technical Instructions
8.9 Activity - Sample Technical Instructions Analysis. Johnson-Sheehan, Richard. Technical Communication Strategies for Today. Second Edition.
20 Technical Writing Examples to Inspire You (Word & PDF)
How Technical Writing Examples Can Help You? As a technical writer, one of your main tasks is to understand the product, learn how to use it, and interpret the instructions provided to you by the developer, manufacturer, or creator.
7. Writing Instructions
Writing Instructions One of the most common and one of the most important uses of technical writing is instructions—those step-by-step explanations of how to do things: assemble something, operate something, repair something, or do routine maintenance on something.
Technical Writing Standards
When writing technical documents, engineers rely on style manuals, which provide standards for writing and designing documents. Style manuals ensure consistency in writing and formatting documents written for academic or workplace communications. Academic disciplines, including academic journals, have their own style manuals.
Professional and Technical Writing/Instructions
When writing technical documents and instructions there are several style tips you should keep in mind: Use a lot of imperative, command or direct address, kinds of writing. It is OK to use "you" when writing instructions, because you are addressing the reader directly. Use active instead of passive voice.
7.7 Writing Instructions
7.7 Writing Instructions. One of the most common and important uses of technical writing is to provide instructions, those step-by-step explanations of how to assemble, operate, repair, or do routine maintenance on something. Although they may seems intuitive and simple to write, instructions are some of the worst-written documents you can find.
1: Introduction to Technical Writing
Technical writing is an audience-centered means of communication that provides a reader with clear and easy access to information. In the business world, time equates to profit, and profit is the force behind all professional interactions. The technical writer and reader have a vis-à-vis relationship.
What Is Technical Writing? Definition, Examples and Steps
Discover what technical writing is, view examples of this communication style and learn how to pursue a career in this specialized field.
Professional, Technical Writing
Professional, Technical Writing These OWL resources will help you conduct research and compose documents for the workplace, such as memoranda and business letters. This section also includes resources for writing report and scientific abstracts.
Writing Essays
The current chapter focuses on essays, pieces of persuasive writing developed around defined topics. This genre's persuasiveness rests in large part on its logical structure, inclusion of quality evidentiary support, and consistent design, as explained herein; hence, essay writing calls for planning, researching, synthesizing, and revising.
Technical essay style guide
Technical essay style guide This class will provide you with many opportunities to practice the art of technical essay writing. Here are some simple guidelines you can use to avoid common problems.
Writing Technical Instructions
Learning to write technical instructions is challenging. Writers must consider audience, purpose, context, length, and complexity—plus the specific content of the instructions, such as the steps in using a stapler. In this lesson, students walk through the process of creating technical instructions by first analyzing existing instructions.
Technical Writing Examples for Students
Technical writing is a type of writing that helps someone solve a problem or acquire necessary information about a specific subject. Examples of technical writing include instruction manuals, recipes, how-to guides, text books, multimedia presentations, and operating instructions.
English 305
You must submit your essay before registering for the final. Below you will find prompts and instructions for submitting your assignment.

A Guide to Technical Writing (With Examples)

What Is Technical Writing?

Instructions for Carrying Out a Task

Operating Manuals for Machinery, Appliances, or Systems

Specialized Topics

So How Do I Produce a Great Piece of Technical Writing?

Who Is It For?

What Do They Need?

How Should Technical Writing Be Composed?

Find this useful?

Examples of Technical Writing

Is technical writing difficult?

Are there professional bodies for technical writers?

What can I do if I’m not sure that my technical writing style is appropriate to my subject?

Share this article:

Got content that needs a quick turnaround? Let us polish your work. Explore our editorial business services.

Free Email Newsletter Template (2024)

How to Write a Nonprofit Grant Proposal

How to Use Infographics to Boost Your Presentation

Why Interactive PDFs Are Better for Engagement

Seven Key Strategies for Voice Search Optimization

Five Creative Ways to Showcase Your Digital Portfolio

Make sure your writing is the best it can be with our expert English proofreading and editing.

Technical Writing Examples

What does technical writing mean?

Technical Writing Samples

Characteristics of technical writing

What is the purpose of technical writing?

Technical Writing Skills

Where is technical writing used?

Tips for technical writing

More Templates

Newspaper Templates

All About Me Templates

Plot Diagram Templates

Essay Outline Templates

Table of Contents Templates

Envelope Address Templates

The Whatfix Blog | Drive Digital Adoption

11 Technical Writing Examples & Samples in 2024

What Are Common Examples of Technical Writing?

What Is Technical Writing?

Types of Technical Writing

1. End-User Technical Writing

2. Expert-to-Expert Technical Writing

3. Process Documentation Writing

4. Technical Marketing Communications

What’s the Difference Between Business Writing & Technical Writing?

11 Examples of Technical Writing in 2024

1. User Manuals

2. Software Installation Guides

3. Standard Operating Procedures (SOP)

4. API Documentation

5. Service Level Agreements (SLA)

6. Press Releases

7. Case Studies & Whitepapers

8. Company Documents

9. Request for Proposal (RFP)

10. Annual Reports

11. Business Plans

What is Technical Writing? A Comprehensive Overview

Carla Wardin

Table of contents

Writing and Communication

Accuracy and attention to detail

Organizational skills

Snagit for screen capture and simple recordings

Annotate and edit screenshots with Snagit

Camtasia for polished training videos

User manuals

Standard operating procedures (SOPs)

White papers

Case studies

The best snipping tool for Windows and Mac

Speed up your screenshot workflows

Additional Resources

Writing Instructions

Types of Instructions

Getting Started

Focusing Instructions