5.2: Popular Genres in Technical Writing

Popular Genres in Technical Writing

Having looked at a method to investigate genres, I want to shift our focus in the back half of this chapter to introduce you to a few specific genres in the world of technical writing. This will be a brief overview, giving you a window into what the general gist and goal of these genres tends to be in my experience as a writer, instructor, and researcher. Please note that between cultures and companies these documents may be drastically different—these are really just some popular conceptions of the genres themselves. To really dig into what they look and feel like, you’ll need to do some original research. Surprised? Probably not at this point in our text.

I’d like to briefly cover some key players in technical writing circles: proposals and grants, white papers, reports, technical descriptions, instructions, and manuals. This is by no means an exhaustive list of genres—you’ll find an almost endless supply of them out there. This is also by no means a definitive definition of each, but I think each overview will give you a window into the ways that these genres work and the types of problems they were invented to solve.

Grants and Proposal

Grants and proposals are one of the most action-oriented genres that you can work with in technical writing, though they often also tend to be some of the most rigorously defined by forces outside of your control. A grant or proposal often comes from a specific solicitation by a funding source that is either looking for a particular project to be completed for them or looking to support projects that complete certain goals.

In a corporate context, proposals will be solicited for various jobs an organization might need. For example, I might put out a request for proposals and bids to create a new computer lab infrastructure in my building on a college campus. In this case, I’m soliciting folks who will complete a particular task and tell me how they’d go about doing that and what their budget would be, guided in all of this by my own suggestions and guidelines.

The world of grants can be quite different because grants are often not designed for a particular activity: they are instead designed to promote a type of activity. For example, there might be a civic beautification grant available in a large metro area that solicits projects from local artists to create public artwork that enhances the town and tells part of the local story to those that interact with the art. For the funding agency, giving these grants out is a way they can encourage and bankroll a particular type of activity without actually completing that activity themselves. It offers a way to make use of funding to influence activities without jumping into the business of doing a particular activity or pushing for a particular cause.

In some cases, grant funding agencies have a very particular set of values that they advocate for, or a very particular way of having projects completed, such as mandatory partners on a project. Be aware of these goals and values—they may not always mesh with your organization’s values and skills. Almost any grant funding organization has an agenda for their funds, and it is entirely fitting that they would—it is their money after all. Just be aware of this and the issues it can raise. (For example, getting funds from some organizations may be more politically hazardous in certain areas than others, such as getting funding from an organization that supports charter schools and school choice in an area that is strongly against such measures).

Generally speaking, a grant or proposal has a few major sections, though the sections will always be contingent on the funder of the task at hand. The call for grants or proposals will tell you what should be submitted, what is needed, and sometimes will give you an insight into what matters and why. You simply must follow these recommendations. They are not optional! When a grant or proposal is judged, it will be judged by these rules and recommendations. Anything that doesn’t fit will be discarded—an easy way to winnow the pile of applications.

Your goal with a grant or proposal is to show how you’d fulfill the goals of the call for proposals in a way that meets the needs of your funder. You need to show you understand the current situation, that you have a clear plan for action, that your group is competent and trustworthy for this type of work, and that you have a legitimate budget and timeline. Beyond these you may have some specific sections and deliverables requested, but usually any grant or proposal will give you a chance to talk about these types of subjects.

A good grant or proposal has a narrative structure. This doesn’t mean that it’s suddenly story time and it was a dark stormy night. What I mean is that you’ll want to have an overarching narrative and theme to your work. You will frame the problem in a way that makes sense for your solution. You’ll frame your past work in a way that shows your ability to complete this current task. In short, you’ll be persuasive. There are any multitude of valid and honest ways to tell the story of a grant or proposal; you’ll just need to pick the right one for your situation. Again, this isn’t a call to stretch the truth—lies and misdirection in a proposal is a great way to get into legal trouble or blacklisted. Instead, this is a reminder that your presentation of “the facts” is not enough.

You need to think about the context and who you’re writing to and why. If you’re offering new technology, you can frame the current technology as out of date. If you’re offering green technology, you can frame the current technology as excessively energy intensive. Each of these frames is a valid one, but the pairs I’ve created make more sense than framing the current technology as outdated and offering green technology or framing the current technology as inefficient and offering new technology. Remember that this is a competitive genre and you need to make the best and most accurate case possible for your team.

When you’re looking at how to frame things, look for what your organization values, what you’ve excelled at, and what the funding group values and what they excel at and ask for. You’ll often find a way to draw connections between your group and the funding group. In some cases you won’t be able to make many if any connections—this can be a sign this grant or proposal is a bad fit.

As a final note, and one that goes with all genres that we’ll discuss—do not use boilerplate texts. Don’t create a generic grant application and send it to everyone with a few names changed. This is a great way to fail at grant and proposal submission. No one likes boilerplate texts and boilerplate texts are incredibly obvious in their overly generic approach to everything. Take a little time and customize your texts to the situation and you’ll go much further!

White Papers

White papers are an odd genre, one that is not universally present in professional communication, but one worthy of noting. At its core, a white paper is a sales document, one that is designed to motivate someone to make a purchase. What is intriguing about a white paper in our context is that they are usually designed to educate someone enough to make them desire your current product or service. You can and should make a pitch for your organization, but usually after educating someone as to why it would be of value at all. (Note: white papers are not the same outside of the US. You may run into other documents called white papers that are totally different. Cultural context matters!)

To help explain how white papers work, I’ll give you an example from my own background. Growing up, my father was the third generation owner of the family tire repair business. When I was younger, the primary work the shop did was the repair of damaged tires and the purchase of new tires. You could also get maintenance work like balances and rotations. At the time though, oil changes weren’t even on the menu. During the 90s, my father started getting white papers from companies selling machines for front and rear wheel alignment. These white papers came with informative models that you could use to demonstrate what an unaligned tire would do to a vehicle and generally educated you on the value of wheel alignment on the life of your tires. It also made the business case for wheel alignment and advocated for a particular machine from a particular manufacturer. After reading the documents and talking with sales folks, my father purchased the machines and from that point on his business had wheel alignments as a service.

In the context of the 90s, wheel alignment wasn’t something that a traditional mom and pop tire shop would have covered. It required specialized equipment that was not cheap, and it required special training for operators of that equipment. Getting a mom and pop shop to buy the expensive equipment directly wasn’t a winning strategy—the price alone could spook people. Instead of making an immediate sales pitch, white papers and strategies tailored around education allow the manufacturers of this equipment to explain the importance of and sales potential of the machinery in order to help the audience to get to a point where they understood the technology enough to make an informed choice.

White papers are often used in areas where technology is advancing in a way that needs explanation. If you’re offering a new piece of software or a new type of service, you may very well need a white paper to make the case for your approach. White papers don’t make as much sense in established areas with established technology that you’re going to be selling to folks. If you have a new spin on that technology, maybe a white paper makes sense. Otherwise, it’s not going to be that useful.

Reports

We’ve already hit on reports, and so I won’t spend that much time on them here. Suffice it to say that reports are documents that give someone information on a process or series of events or a plan, anything really, and then allows the person who has that information to make decisions or advocate for decisions or courses of action. If you want to blame someone for reports, blame a business major—a large part of the logic behind business majors is that they are experts at decision-making in business environments, aided by reports as part of their understanding of what is going on and what they should be doing. The rise of reports came along with the rise of the professional business major, allowing information to move beyond people and into paper and other sources.

With any report, ask yourself who is going to be using this document and what they’re going to be using the data for. This can vary depending on who is reporting and why. You may be tasked with a feasibility report on a project—in this case, you’ll be creating a report that helps decide what actions are available and whether they make sense. You can also see reports generated by openly or not-soopenly political organizations that have very particular values and goals behind their reporting. Not all reports are created equal.

When reporting anything that caries a value judgment, the most important thing you can do is create a set of criteria. If you set up the criteria and define them, you can have a productive discussion because you’re making a case for what measures matter and then using those measures to make a judgment call. If your audience agrees with your measures, all the better. If they don’t, you’ll need to make the case for your measures. Without criteria, your report mostly stands as opinion. I have an opinion, and you have one too. Opinions are great, but when we judge them based off specific criteria we can debate on, we can have a constructive dialog. If we’re just railing at each other’s opinions with no overarching context to create judgment and value, we’re not going to get far. (Just watch some political talk shows and you’ll see this in action very quickly).

Technical Descriptions

A classic of technical writing that is often associated with engineering, technical descriptions are fairly self explanatory—they are a technical explanation of how a particular system or device works. The use case for descriptions can vary, depending on who is going to make and share the description. For example, there is a thriving online world of folks that reverse engineer and build their own guitar pedals (effects devices that modify signals for distortion, compression, modulation, etc.). A large part of this community is sharing how a particular pedal works and what the components are within a given pedal, so they share a lot of domain-specific technical descriptions.

Technical descriptions are one of those genres where you may well get a chance to really get into using your field-specific terms and language because they are designed, often, for folks that are already experts or who at least know enough to read through the text. This isn’t always true, but it can be many times. Here is a simple technical description of how the LED connects to a guitar pedal, badly drawn by your author:

Now, this particular technical description is entirely visual—that isn’t to say that all technical descriptions are, but you do find visuals as a component in the genre. This is a particularly awful description because of my color choice on the black wire between the LED and the switch—you notice it overlaps the minus symbol, making it unclear as to whether it is positive or negative. In addition, I’ve neglected to include a resistor in this schematic, making it very likely my LED will burn out quickly and be ridiculously bright. But, this crude drawing could very well accompany some text like the following:

“In this pedal the LED is connected directly to a wall-mount power supply input. Not pictured here, a resistor is located between the power supply and the LED, regulating the output of the LED and preventing premature burnout. The ground of the LED connects to the foot switch—several other grounds from the PCB and the input connect here as well.”

In this simple explanation, you get an idea of what is happening in the design. This isn’t very technical, but it does tell you what is happening in this particular system of a pedal. That can be enough in the hobbyist’s world where you simply need enough understanding to make things happen electronically without mishap. In the world of electric engineering, this would likely be entirely insufficient. Audience and context matter.

Anytime you’re going to describe a system or a process, technical description as a genre can come into play. It isn’t the most glamorous genre, but it has a useful purpose and helps folks understand how things work.

Instructions

It’s come to this. Instructions. You knew they were coming, right? If any genre is associated with the teaching of technical writing, the genre of instructions would be the one.

When we think about instructions, we want to think about them as tools for use—not those things you throw away because you don’t need them or can’t read them. Instructions get a bad wrap because too often they are designed as an item in a checklist that needs to be completed rather than as an essential part of any project that is oriented around sequential tasks. Good instructions can be a true joy to use, but we so often end up with the phoned-in-at-best variety that perhaps has lead many of you to despise the genre.

Time for a brief confession—I truly love instructions with all of my being. To the very depths of my soul, I love instructions. Why, you may ask? They help you do things. They tell you how things are supposed to be done. They put order into a situation. I like following instructions and I like making them because of this. I find special pleasure in good instructions that are thoughtful and useful, like so many are not. I like instructions because they take a process that might be challenging or tedious and make it easily understood and perhaps even educational. (As a side-note, I’m also a huge do-ityourself person having built my own computers since I was a teen and having most recently tiled my bathroom floor after some intense research. I like learning about things and how to do things and instructions make that possible).

The biggest challenge with instructions is one of perspective—you often don’t see a task that you’re good at correctly. Think about starting a car and putting it into reverse or putting your key into your lock and unlocking your front door at your dwelling place. These are tasks that you do all the time, and as such you tend to internalize entire steps to muscle memory. It’s kind of like when you start walking or driving somewhere and accidentally end up going to your normal destination when you meant to go somewhere else but managed to get a little absent minded. Instructions often suffer from this phenomenon because they internalize and omit steps that are essential to newbies.

The best thing you can do is to take a literal approach to your instructions when testing. If they don’t say to do something, don’t do it and see what happens. You may find quickly that you’re overlooking key things like pressing the brake pedal when you shift from park to reverse when driving. This type of testing will get rid of your blind spots by forcing you to run into them.

The best thing you can do outside of personal testing is to find someone who truly doesn’t understand what you’re trying to explain. This can be hard with simple tasks, but if you can find a test subject or four you can find out quickly through various research methods what is going on and where things are breaking down. The final chapter of the text offers you a number of solutions.

Finally, remember that the best instructions offer a clear view of the process that is taking place and how each step comes together as part of that process. You’ll find folks have an easier time with things when they know where they are going and what their progress is. In addition, useful illustrations and even things like color coding of steps and repeated processes can make things much easier for anyone actually using your work. Remember—instructions are used to do something. Make sure they are designed around that use!

Manuals

If there ever was a genre that was the opposite of glamorous and exciting, I think manuals would be that genre. Manuals get a bad rap I think because they aren’t designed for reading, and we tend to judge most large texts by their readability rather than other metrics like use. Manuals are a reference tool rather than a relaxing read to pore through while you sit in the hammock and sip lemonade. They are designed to be searched to find information about a specific part of a process or system or procedure or to solve a particular problem.

Manuals should be judged by how they help you fix an issue or understand something, not by their capacity to entertain. For example, if you have a flat tire you’ll reference your car’s manual to find out where your spare is and where you jack is located (if you have one instead of a can of flat-fixing goop). You might also use a manual if you need to know how to format say, a television show when using Chicago style.

Like instructions, manuals can be annoying to use because they can be designed as an afterthought. We’ve almost trained ourselves in many circumstances to avoid manuals, and that can be a huge mistake! A good manual can be a powerful tool to help you through a complex process.

Practically speaking, think about a manual in a professional capacity as a barrier against having to do tech support of some type. A good manual helps folks understand systems and troubleshoot common problems without getting overwhelmed. A great manual does this in a clear, well-documented and illustrated way that allows easy identification of information that is helpful and avoidance of information that isn’t helpful.