"

1 Introduction to Technical Writing

Week 1 Lecture

Hey associates, this lecture is about technical writing and presentation as a form of communication. It is an overview of our field, and this class, focused on STEM, professional, and business writing contexts. You can listen along to the podcast episode, which has the same content as this chapter (you are currently reading a formatted transcript of the podcast lecture).

 

The lecture has three sections:

  1. Technical Writing as a Discipline and the differences between that and essays or school writing you might be used to creating,
  2. the Styles of writing with a preview of the common genres,
  3. Ethics.

I’ve provided a notetaking guide you can download to organize your thoughts and Big Actions–the “what will I do because of this information.” At the end of each section, you will see a blue box to stop at and check your notes as I recap big points.

Recap Sections

I will list the topics and key points you need notes on in these blue boxes. This box doesn’t replace reading the section; it is just a guide to help you check your notes.

  • Try different styles of notetaking! You can doodle, make cartoons, create a slide deck, color code your points, and use interactive tools like OneNote (which allows making flashcards) or third parties. Don’t limit yourself to a bullet-point list–if you find that boring or ineffective. Take control of your learning and make it more engaging, creative, and useful.
The avatar of Professor HB with a red cape standing on a building like Superman.
Be your own hero and take control of your learning. Do whatever works for you to pay attention, understand concepts, and make connections.

I recommend stopping and returning another time to stay fresh and focused after reach section. These are full lectures meant to replace or be equivalent to sitting in class for a full period. But unlike sitting in a lecture hall, where you have to focus the whole time, you get to pause, rewind, leave, and return to the information on your own time. Use that control intentionally to break up the information over the whole week and stay focused in smaller chunks. Asking your brain to stop and re-engage with concepts multiple times over the week, which naturally leads to revisiting past notes and thinking about where you are at, is a sneaky study strategy that helps process information. Don’t power through and half-listen in one sitting. Do what you want, but also set yourself up for more success.

Section 1: Technical Writing as a Discipline

First things first: this class for the technical and business context of writing is a whole different category than ESSAYS. You are NOT writing essays for any project or situation in this course. Each has its purpose, place, and use. Essays show the reader how much you know, understand, think, and even argue about a topic. They are super efficient ways for a teacher to see how much you take in from a lesson, which is why they are so common in school. But in this class, I’m not grading or judging how well you know a specific topic; I’m looking for how well you demonstrate our strategies of writing styles, genres, and STEM situations.

Beyonce singing No, No, No in a yellow hoodie on stage at a concert.
No essays, please. This is a different writing style and context.

The difference between essay writing and technical writing is apparent in three ways (✨write these things down!)

  • ✨The goals of the work. Essays are writer-focused because your audience is interested in understanding how well YOU know the material with your thoughts, experience, analysis, and interpretations. The audience in technical writing expects reader-focused work because they want to accomplish their goals with content that serves their needs. So, often, essays are what YOU want to say, while technical writing is what the reader NEEDS for their work and tasks. The better you align the project with the situation I provide–it will be a CAMP site, which stands for the context, audience, message, and product–the stronger your score will be as you reflect consideration for the readers.
  • ✨The way it is read. Essays are primarily narrative, meaning each sentence and section builds on the previous more or less sequentially. We expect the audience to read all your words in the order written to follow your train of thought and commentary. They aren’t constructed to skip around as much. In technical writing, the audience usually skips around to find content and often consumes a fraction of all the information available. We construct all of our documents and products in a tech writing situation with the mindset that they might read it in order–and it certainly makes the MOST sense and value if they do–but that, realistically, they will and can pop around. So, we do need to recap really important elements and format them in specific ways that allow for that pattern.
  • ✨This leads to the most visible difference because of the purpose and audience distinctions: How documents are formatted. Essays are typically written as paragraphs of text because we expect the audience to read them all through. You might have a few major headings, but the transitions into your new ideas mostly exist inside of the writing and rely on your sentence and paragraph construction. In an essay, “formatting” mainly refers to margins, font styling, line spacing, and other type-focused elements. Technical writing is designed for readers to skip information, scan pages for context, and skim with quick processing. We use far more headings, symbols, boxes, and graphics to guide the reader. When we talk about formatting it is a deeper “document design” or “information design” strategy that presents the information to the reader. We use all those tools to create a path or guide for the reader to make it easier, faster, and clearer for them to search for the topics.

Overall, when creating a technical document, we need to make it easy to skip, scan, and skim. People don’t super want to read your stuff: they have to because there is a specific job, goal, or actionable information that they need. Their patience is typically thinner than most other audiences–think of your favorite book…it is just words and words, but you actually WANT to read what happens to your characters. Think of an essay in the New Yorker or an Op-Ed in a paper…people read those because they want to; otherwise, they just skip it. And your professors who ask for an essay want to know how much you understand and interpret the unit they taught. But when we get an email, a manual, or a technical research paper….we usually read it for very specific information, instruction, and action.

 

So, big picture–you aren’t writing essays. So then…what are you writing, and what qualities and foundations do our technical writing genres show?


1.1 Qualities of Technical Writing

I will use the term ‘writing’ throughout the lectures, so we do need to stop and define or recognize what we mean. Writing or a document and text refers to any product we create for technical communication—so all these ‘writing’ concepts can be applied to our growing multi-media landscape. Often, technical writers are creating videos, podcasts, social media posts, infographics, posters….. Things that are beyond the typical writing you might picture. It is easier and faster to say ‘writing’ or ‘document’ than to list all those contexts every time.

So–and write this down in your notes– Technical Writing and Presentation means producing any form of user-focused, action-oriented communication, including print, digital, interactive, and audio/visual material created for STEM, Business, and Workplace contexts.

When we think about the ‘presentation’ of information… it can mean standing up in front of people and speaking a form of presentation, yeah, but I’m referring to the overall delivery of your information. How you present it on the page, the slide deck, and the screen. When you write a progress report, you present information to the reader.

With those definition items out of the way, we can turn to the key characteristics of all technical writing. I have three words I want you to remember for your work:

  • Useful: Most people don’t want to read what we make. Instead, they’re reading it because they need to. So our work has to offer value to them. We maximize the value by addressing particular readers—while anyone or everyone COULD access the content, we aren’t designing it for ‘everyone’ (which then makes it less useful to anyone). Instead, we are comfortable and strongly saying this version of the document is for this target audience, who will find it the most useful. Our products also need to solve problems and offer information that the reader can act on. For something to be useful, it must be correct, accurate, and understandable. So we do need to adjust how we explain the topic to fit the reader. Even in this course–which is an introduction to these topics–I will simplify and make decisions on how detailed and specific, and nitpicky I get when delivering information: I focus on remaining correct while trying to keep it more useful to your broader careers, interests, and skill levels.

Sure, it might be the most correct or accurate to give a 10-page deep dive filled with all the most technical terms and tiny details of how ‘lift’ is achieved in an aircraft…and the engineers, mechanics, and safety inspectors might require that level of detailed accuracy. But if you are writing to the customers of your airline who are interested in how flight happens and worried about safety after a malfunction or recent crash, it is also CORRECT and more useful to simplify the physics into core points with relatable explanations.

  • ✨Useable: As your notes should already outline, our audiences must skip, scan, and skim the content to find the answer. So, useability refers to the readability and control of the document. We want to give readers the tools–through our headings, symbols, graphics, navigation, labels, captions, callouts, and so many more options that we will get into this semester–to control their experience. The useability also considers the environment in which they will use it. Finally, useable refers to our legal and ethical responsibility to accessibility–ensuring that users with diverse physical and psychological needs can use the content–considering how those with disabilities or less-typical situations can interact with your content.

A field tech out in the rain, wind, and dirt might need a physically printed and laminated version of the manual to be useable compared to someone always in the office accessing content on a computer with internet and speakers. Giving the field techs a video tutorial would be less useable if they can’t hear it over the wind, can’t see it as well due to sun contrast, and maybe can’t play it without service or Wifi. And the office user might find a printed copy less useable when all their other work is saved on their computer, and they can listen to or follow along with video while they troubleshoot.

  • Enjoyable: Obviously, there is a limit on ‘enjoyment’ within our contexts. So think of it like this: make the work as enjoyable as possible. Don’t put too much of a burden on your readers to get what they need. We need our documents, whether it is an email, a presentation, or a long-form report, to do a few things that make it a more enjoyable experience:
    • Effective documents will make a good impression: They will be readable, organized, and neat. Being readable, organized, and neat means that our audiences can jump around our documents to find the information they need in that moment to make a decision and take action.
    • Effective documents will make sense to the reader: To create things that make sense, we need to have a clear purpose and a clear plan for our document to get it to that purpose. Planning helps create a logical order, layout, and design. When people don’t understand the purpose of a document, they tend to enjoy the experience less.

As you move forward with your technical writing, repeat those words like a chant: useful, useable, enjoyable. Useful, useable, enjoyable. Make it useful, useable, enjoyable.

Cartoon HB standing next to an A+ while clapping.
As I grade your projects, I will be thinking about those qualities–and the easier you make my job in locating the required elements and seeing your application of skills and concepts, the more points you will receive.

 


1.2 Visual Strategy

We use a full ‘visual strategy’ to help achieve our goals of useful, useable, enjoyable documents. The visual strategy is the entire visual impact of our document. It is not just about making a document look pretty; it is the strategy–the intentional plan–to help readers use, process, and remember the information presented. We will get way deeper into these principles in the Design Lecture, so as an overview, keep in mind these core principles that are a foundation of Technical Writing:

  • Contrast is a design principle that makes different elements visually distinct. This can be achieved through various techniques, such as using different colors, fonts, sizes, or shapes.

For example, a heading might be made to stand out from the body text by using a larger font size or a bolder weight. Another example of contrast is the use of a red and bold “Danger” note in a manual to draw attention to important safety information that is different from the steps.

  • Repetition is a design principle that uses the same elements multiple times to create a sense of unity and a pattern. This can be achieved through repeated colors, fonts, or shapes, as well as with the structure.

For example, main headings might always use the same font and size so the reader sees the pattern for big topics, or a symbol might be repeated to indicate a glossary term in each section. We also create a pattern for the reader by starting each section with an overview and ending each section with action items (or whatever content structure makes sense for that situation). Humans like order and we do tend to seek out, understand, and remember consistency better.

  • Alignment is a design principle that refers to the arrangement of elements on the vertical and horizontal planes. It can create a sense of order and balance–again, people tend to enjoy and understand patterns and consistency better.

For example, in a bulleted list, the indenting along the horizontal alignment tells us that the bullet point is a sub-point. Or placing the content on a product page within a vertical column–the image, title, description, and price all aligned makes it easier to recognize and navigate the page.

  • Proximity is a design principle that refers to the relationship between elements in terms of their distance from each other. It can be used to create a sense of grouping and hierarchy.

For example, putting the caption right below the image helps us understand that it is describing that image and not something else. Proximity and alignment work very closely together to help show that organization of the page.

  • Size is a design principle that refers to the relative size of elements. It can be used to create a sense of importance or hierarchy.

For example, a larger element is typically considered more important or first in the information set. Our eyes just are drawn to very big and potentially very small things as they stand out in the layout. Size also heavily impacts the usability of a document.

All of these principles are happening on your page whether you design it that way or not. Repetition–or lack thereof–happens, and people look for it. Alignment and proximity exist based on how things are laid out. Size is impacting your content. So, the goal isn’t to ‘create’ alignment. The goal here is to strategize and USE the principles with intention and to work harder for your content. Control the contrast, repetition, alignment, proximity, and size of all the elements on your page through active decision-making.

Recap

We’ve reached our first recap! Please review your notes and ensure you have definitions, key points, and examples for the following topics. Your notes should make sense to YOU with descriptions and applications for your life. Don’t just write down what I said word for word necessarily–tweak it and come up with examples that make sense in your brain and connect to your career goals, hobbies, personal interests, and lives. That connection is where learning and understanding something happens. Not necessarily just from recall or copying.

Your notes should have content for the following:

  • The difference between technical writing and essays. Your notes should talk about three specific things related to purpose, audience, and format.
  • The definition of technical writing and presentation for this course.
  • The qualities of technical writing. You should have written three specific terms with examples of how a document follows these three words.
  • The definition of a visual strategy with 5 main principles to use intentionally and control in your work.

 

 

A person sits infront of a computer stretching their arms above their head. Take a Break! is in bold letters above their head.
Take a break right now! Spread this chapter out over the whole week.

 

We’ve concluded Section 1 on Technical Writing as a Discipline for this lecture. I encourage you to take a LONG break before starting section 2. You should do something—eat, go to class, move your body, or go to sleep–and return when you are ready to refocus. 🎶🎶🎶

Section 2: Styles of Technical Writing

We are starting section 2 of this lecture on Technical Writing Genres as an Overview. The rhetorical situation—basically, the who, what, when, where, and why of your reason for writing—drives every decision we make as technical writers.

2.1 Ways to Present Information

We have four main ways to explain and describe topics for technical audiences. A document tends to fall within or mix 1 or 2 categories–but they aren’t necessarily exclusive. We can also talk about the same content in one way for one audience and then use that same topic differently for a different audience. These four ways: scholarly, functional, interpretive, and affective also don’t rely on the medium. We can have super scholarly YouTube videos just as we can write a lengthy report interpretively.

So, I’m going to define and explain the ways, and then, after, we will go through some examples.

 

✨Scholarly

This form of explanation focuses on the theoretical or academic components of the topic with heavy jargon. The scholarly presentation is really meant to be more useful, useable, and enjoyable for other informed, expert-level readers. It is a way of explaining things to people who need to REALLY, really know a topic, including all the history, influences, and little details. Since the reader of a scholarly presentation is expected to have a lot of prior knowledge and motivation for engaging with the work, we don’t necessarily stop to define every specialized term and will use that jargon as shortcuts that still keep the very niche in meaning.

Examples of scholarly presentation of topics would be academic research papers, which are written to explain and present data to other researchers. It will usually be very dense, with detailed sourcing for all the background, context, and outcomes.

 

✨Functional

This form of presentation focuses on the topic’s practical components using jargon. The functional description is meant for practitioners–people directly working with the subject who need to really understand how and why it works. They are expected to have prior knowledge and motivation to understand the topic, including familiarity with specialized terms.

Functional presentation is more common for trade journals written to explain industry topics to people working in the industry or things like proposals and documentation within a field. Your ReadMe files for code and technical descriptions for the devs and engineering teams are forms of functional work.

 

✨Interpretive

This form of description focuses on explaining the components using more general terms. It is like the more simplified version of the scholarly and the functional and meant for audiences who are just learning about a topic or only kind of need to know how and why things work. They don’t necessarily THE details to really KNOW, know the topic. They just need enough to understand the big principles and get the job done.

We would use the interpretive style or presentation for end-user documentation like user guide and tutorials where all the specialized terms are either avoided or defined and the reader learns more on how to use the product rather than why the product works in detail. A textbook for a class is also a good example of interpretive because it is usually a high-level introduction to the topic with plenty of definitions, examples, and simplified explanations to help you learn. Once you get through a textbook on the subject, it is easier to understand the more functional and scholarly documents.

✨Affective

The final form is focused on sharing an experience and really relating to the audience. It is the most easily understood by the widest audience type and is meant to create a connection, show the use-value, and generate interest in a topic. The audience is generally assumed to be a bit unmotivated or unsure how and why the topic is useful or related to them.

This style is most useful as a strategy inside of larger presentations–like stopping to explain how the product can be used or a solution is so valuable to fund. I do use an affective style during lectures and workshop activities when teaching as a way to introduce and help show the connections with our concepts to your careers or personal life. I like to tell stories from my own experience.

As an example, we can turn to NASA, which does a great job of explaining the same topics in different ways. So NASA has an entry in their Astrophysics Lab index for an AGN. They also have an Instagram post explaining an AGN. I’m going to read the excerpts, and I want you to listen for the differences in how the same concept is presented in a scholarly/functional way and a more interpretative/affective way:

The first excerpt–you can guess where this one is from and what style it is:

“For starters, an AGN is a small area in the center of some galaxies that is far brighter than the galaxy’s stars alone. The brightness is caused by a supermassive black hole heating matter that falls into it.”

Alright– now the second:

“Active Galactic Nuclei (AGN) – An active galaxy contains a compact core, or nucleus, of emission that is embedded in an otherwise typical-looking galaxy. This galaxy nucleus shines at all wavelengths of the electromagnetic spectrum and is seen to be bright compared to the rest of the galaxy. Its light may also be highly variable, and some AGNs even change their major visual characteristics over time. In galaxies with very dense cores, the X-rays from the center can penetrate material outward from the nucleus, and this provides scientists with unique insights into the physical processes occurring there. Our science team performs X-ray observations and modeling of processes in these AGN systems. At the very center of an AGN lies a supermassive black hole. Dense material from the surrounding regions can accrete onto the black hole, releasing large amounts of gravitational energy.”

Did you guess which one was for the lab folks and which was for the Instagram audience? Probably. Here are the features that mark each presentation style:

  • Level of Detail: Scholarly and functional presentations require more detail because the audience needs to understand what is going on. The specific details are less important for the interpretive audience. Both descriptions explain that AGNs are bright. The functional description gets into why they are bright–that it shines at all wavelengths of the electromagnetic spectrum. The interpretive presentation leaves it as it is far brighter–because they don’t necessarily need to know WHY or HOW…just that it is brighter.
  • Components: Alongside the amount of detail is a change in how many factors, causes, and outcomes are included. Both explain how a supermassive black hole is a component of the AGN. But the functional description explains that X-rays observations and modeling is used to understand the features and that is how they know a blackhole exists.
  • Terms: Since the functional audience is assumed to have experience and knowledge in the area–or at least be motivated and need to figure out these specialized terms–that description gets into more physics-oriented language.
    • wavelengths of the electromagnetic spectrum vs. brighter than other stars
    • gravitational energy vs. matter falls into

Both ways of explaining what is going on are correct and complete—one is just more detailed in the accuracy of what really, really and how really the AGN exists and the other is the simplified points.

NASA has one more area where they discuss active galactic nuclei–in the scholarly presentation hosted by their High Energy Astrophysics Science Archive Research Center. Here, they discuss the history of studying this phenomenon, the current state of the research, and all the data that goes into the theoretical and experimental understanding of AGN.

The four ways to present our topics are then used within and across the main genres of technical writing. The combination creates the overall style for presenting our topics to action-focused users. Additional lectures will explore these top genres and cover their features, expectations, use cases, and tools. For now, I just want you to understand the big-picture goals and types of things you would write in the technical communication field.


2.2 Overview of Top Genres

A genre is a form of the product that is recognizable due to the general format, structure, content, and expectations. It is why we recognize a pop album is a different genre of music from a country album. But like pop and country music, we can and do have some cross-over and blending sometimes.

  • Correspondence… emails, memos, letters–the types of documents where you need to share information with a super targeted audience–you usually know exactly who the email or letter is being sent. Sometimes there is more expectation for a direct reply as well (less so with Memos but we will get into in the Project Management lecture).
  • Documentation… progress reports, technical descriptions, definitions, incident reports, and such–the types of documents where we just to capture and reflect what the status or what is going on in a situation. They are focused on describing the state of being or what happened.
  • ✨End-User Materials…instructions, guides, tutorials, standard operating procedures, brochures…the type of documents that command actions and tell people how to accomplish specific task or how to use the products.
  • ✨Analytical Reports…. Research briefs, recommendation reports, usability, lab reports, evaluation reports… I mean the sub-genres of a technical report are vast. They all have a purpose to record, analyze, and share out the insights from data collection processes.
  • Strategic Reports… proposals, operation strategies, business plans, and creative briefs…the documents where we develop and share a clear, logical, feasible model to get things done. Strategic reports are usually more persuasive, as a whole, than the other documents.
  • Media…videos, podcasts, websites, verbal presentations…all the documents that combine audio and visual experiences with more interactions with the user.

Most careers use correspondence (emails, memos, letters) and strategic reports (plans) as a general. The STEM careers–those of you on the engineering and computer science tracks taking the technical writing-focused course–will practice and see more documentation (descriptions, progress reports, incident reports) and end-user materials. Those in the business track taking the business writing course will practice and see more strategic reports (proposals, business plans, marketing briefs) and media, generally. But our project options and lab session will span all 6 major genre categories.

Recap

Before we move onto section 3 about ethics, we need to recap the points and check your notes on the Styles of Technical Writing overview. You should have content and examples for the following points:

  • The four main ways to present information to audiences. You should have the general definition and the type of audience best suited for each style. You should have qualities and an example for scholarly, functional, interpretative, and affective.
  • The markers of style to look for when reading technical work to help you understand what style it is AND what you can consider when creating documents. I broke down the three topics when I discussed the NASA example.
  • The definition of a genre and how to tell one genre from another.
  • The examples of each big genre that relate most to your career goals. So what sub-genres and document types did I mention in each that you might expect to READ, USE, or CREATE in your career.
A cartoon person stretching their arms above their head. Get Up Stretch is in bold red letters above their head.
Go stretch. Seriously. Stop and come back to the last section later.

 

Take a little break and then prepare for this lecture’s final section: the ethics of a technical writer. 🎶🎶🎶


Section 3: Ethics in Technical Writing

Let’s talk ethics– the guiding values and expectations on behavior and conduct for a group. As people, we have some ethics, like the general golden rule:

Don’t be a self-centered, self-righteous asshole who intentionally goes out of your way to harm other people with no remorse or thought of consequence. Just kidding, sort of; we recognize this as “treat others how you want to be treated.”

Generally, that is the ideal. However, we have different ethics based on culture and community that all stack and layer. We even have distinct ethics in the university code of conduct for our community on campus to follow, and I wrote some ethical guidelines into the syllabus for us to follow as a class. Sometimes ethics are clearly written out, and other times it is a learned and implied expectation of a group. So, when we talk about ethics today, it is focused on our guiding values and principles for technical writing, which our Society for Technical Communication outlines. Most professions have an organization that sets the ethics for their field. Try searching for that body for your career goals. For many of you, it might be the IEEE (Institute for Electronics and Electrical Engineering).

3.1 Ethical Principles

How a writer presents information in a document can affect a reader’s understanding of that information’s relative weight or seriousness. Remember our qualities–that people tend to skip and scan around? Because of that tendency we actually have a bit of power in what is potentially missed by the readers and need to have a strong commitment to ethics.

For example, hiding crucial information in the middle of a long paragraph deep in a long document seriously de-emphasizes the information. On the other hand, putting a minor point in a prominent spot (say, the first item in a bulleted list in a report’s executive summary) might be a manipulative strategy to emphasize information that is not terribly important. Both of these examples could be considered unethical, as the display of information is crucial to how readers encounter and interpret it.

Given this context in our work, our society outlines 7 ethical principles to observe. They apply to most workplaces, too. I’m going to read and lightly explain them straight from the STC.org language:

 

✨Legality

We observe the laws and regulations governing our profession. We meet the terms of contracts we undertake. We ensure that all terms are consistent with laws and regulations locally and globally, as applicable, and with STC ethical·principles.

 

✨Honesty

We seek to promote the public good in our activities. To the best of our ability, we provide truthful and accurate communications. We also dedicate ourselves to conciseness, clarity, coherence, and creativity, striving to meet the needs of those who use our products and services. We alert our clients and employers when we believe that material is ambiguous. Before using another person’s work, we obtain permission. We attribute authorship of material and ideas only to those who make an original and substantive contribution. We do not perform work outside our job scope during hours compensated by clients or employers, except with their permission, nor do we use their facilities, equipment, or supplies without their approval. When we advertise our services, we do so truthfully.

 

✨Confidentiality

We respect the confidentiality of our clients, employers, and professional organizations. We disclose business-sensitive information only with their consent or when legally required to do so. We obtain releases from clients and employers before including any business-sensitive materials in our portfolios or commercial demonstrations or before using such materials for another client or employer.

 

✨Quality

We endeavor to produce excellence in our communication products. We negotiate realistic agreements with clients and employers on schedules, budgets, and deliverables during project planning. Then we strive to fulfill our obligations in a timely, responsible manner.

 

✨Fairness

We respect cultural variety and other aspects of diversity in our clients, employers, development teams, and audiences. We serve the business interests of our clients and employers as long as they are consistent with the public good. Whenever possible, we avoid conflicts of interest in fulfilling our professional responsibilities and activities. If we discern a conflict of interest, we disclose it to those concerned and obtain their approval before proceeding.

 

✨Professionalism

We evaluate communication products and services constructively and tactfully, and seek definitive assessments of our own professional performance. We advance technical communication through our integrity and excellence in performing each task we undertake. Additionally, we assist other persons in our profession through mentoring, networking, and instruction. We also pursue professional self-improvement, especially through courses and conferences.

In the big picture, that comes down to one big thing: ✨Do Not Mislead✨

As writers, we hold some power since we always decide what, where, and how to present information. Everything is a calculation and decision, so with [some] power, there must also come some responsibility.

Comic book panel with Spider-Man.
Amazing Fantasy #15 (created by Stan Lee, Steve Ditko, Stan Goldberg, and Artie Simek). https://www.marvel.com/comics/issue/16926/amazing-fantasy-1962-15

Thorough research requires a writer to integrate information from a variety of reliable sources. These sources should demonstrate that the writer has examined the topic from as many angles as possible. This includes scholarly and professional research, not just from a single database or journal, for instance, but from a variety. Using a variety of sources helps the writer avoid potential bias that can occur from relying on only a few experts. The risk of intentional or accidental manipulations is most common in the visuals. Remember to provide appropriate context and perspective as you prepare your graphics. Graphics will usually be the first thing a reader notices about your document–and might not stop to look at the scale or think as hard about whether the graphic choice is representing the story best. Again, we have an entire lecture about data visuals, so for now, just understand that ethics will come back in a big way for that unit. Don’t mess with graph types’ scales, orientation, and expectations to avoid these manipulations.

Last, don’t misrepresent facts or just “twist” numbers to favor your opinion and objectives. Once you are on the job, you cannot leave out numbers that show you are behind or over budget on a project, no matter how well it may work once it is completed. Be cautious when using figures, charts, and tables, making sure they visually represent quantities with accuracy and honesty. Within misleading, we have to discuss and consider research and citation practices.

 


3.2 Legal Considerations

Apart from the general ethical principles, which aren’t necessarily enforceable, we also have legal requirements for ethical behavior.

 

✨Protecting Consumers

Documentation should prepare readers to use the product safely. US law stipulates that a manual must list any hazards that may occur “from the intended or unintended but reasonably foreseeable use of its products.”

You have a legal duty to warn consumers when:

  • The product supplied is dangerous
  • The danger is or should be known by the manufacturer
  • The danger is present when the product is used in the usual and expected manner

Failure to “adequately” warn consumers opens your company up to lawsuits. What exactly makes a warning “adequate”? Good question. Adequacy is almost impossible to define. It is much easier to define what is not adequate. Here are a few common ways that manuals or instructions fall short:

  • Failure to warn users about how to use a product properly
  • Failure to warn against risks from the proper use of a product
  • Failure to warn against any reasonably foreseeable misuse of a product

The key commonality is that everything listed could result in bodily harm or death. It is why we have things that seem obvious or even ‘silly’ like…

Danger: placing your fingers inside the yellow safety zone may result in losing a limb.

Safety information must also be accessible to your readers. Therefore, warnings should stand out from the rest of the documents, possibly with icons, colored fonts, or bolding. They should also be easy to understand. A confusing warning is just as bad as not warning users at all.

 

✨Liability and Copyright

Liability law is a legal framework that places an obligation on companies and organizations to conduct their operations responsibly. This includes requiring these entities to provide comprehensive instructions and adequate warnings to users about any potential risks associated with their products. If a consumer sustains an injury or if damages occur due to the use of the product, the company or organization can be held legally responsible and be subjected to liability. This legal principle serves as a form of consumer protection and incentivizes companies to prioritize product safety.

Warranty ties into some liability considerations. There are usually two kinds: express warranty and implied warranty. An express warranty is a clearly written or oral statement of what a product is capable of and the guarantee from a seller to a buyer that the product will meet these quality and reliability standards for a specified time. The implied warranty is connected to your product fitting the intended purpose and meeting buyer expectations. The implied warranties are often established through how the packaging is done and what is on the accompanying materials. Be very clear and cautious of claims that your packaging may make that constitute a warranty and may not be supported. This is why all vitamins and supplements have statements about the “effects being unverified” or “not supported by the FDA” to let consumers know that, technically, the claims are not fully true and protect the company.

Liability and contract laws can vary by country. If you plan on selling wares internationally, account for various regional requirements. Learn about liability concerns before you publish your manual or documentation. As always, consult a lawyer for specific information on constructing warnings.

Copyright– and gaining permission to use intellectual property– as well as protecting your company’s property is a concern, too. We will discuss copyright in the Technical Graphics lecture in-depth since visuals are the more common use or need for copyright permissions. Copyright covers everything you create, and you don’t need to register it to be protected. If someone uses your work without permission, you can take legal action for copyright infringement. Registering your copyright makes it easier to go to court if needed, though. The same goes for using other people’s work. When using someone else’s graphics, getting their permission first is important. Now, copyright infringement needs to be initiated by the holder.

As employees, typically, everything you create at work belongs to your employer as the copyright holder. Often, there is a clause in your hiring contract that outlines how anything you make using company materials and time belongs to the organization. This is why it is super important to keep your WORK and any personal projects that you hope to sell or whatever completely separate. Do NOT in any way work on your own ideas using company stuff or company time. Read your contracts carefully because you may see language around competition and developing new ideas, products, or whatever too closely related to your job and position addressed.

 

✨Digital Accessibility

Finally, digital accessibility is a key legal consideration for writers. We will have a full lecture on digital accessibility because it is so important–both ethically to support inclusive documents and legally to adhere.

Digital accessibility involves creating content that is accessible to individuals with various disabilities, such as visual impairments, hearing impairments, cognitive disabilities, and motor disabilities. This includes providing alternative text for images, transcripts for audio content, closed captions for videos, and ensuring that content is compatible with assistive technologies like screen readers and keyboard navigation.

From a legal standpoint, digital accessibility is protected by various laws and regulations. In the United States, the Americans with Disabilities Act (ADA) requires that public entities and businesses provide equal access to their electronic content. This means that websites, online documents, and other digital content must be accessible to individuals with disabilities–and your company can be on the hook if you miss those standards, especially if you work for a public service like a government or educational setting.

Beyond the legal implications, digital accessibility is crucial for ensuring that everyone has equal access to information and opportunities. Inclusive documents promote social justice and equity by allowing individuals with disabilities to participate fully as the standard without having to request accommodations or feel that extra burden. They can access educational resources, job opportunities, and other essential services without barriers.

Writers have a significant role to play in promoting digital accessibility by creating content that is easy for everyone to understand and navigate. This involves using clear and concise language, structuring content logically, and providing alternative formats for different disabilities. By incorporating digital accessibility into their writing practices, writers can contribute to a more inclusive and equitable digital landscape.


3.3 Logical Fallacies

The final topic in this section on ethics is a discussion of common logical fallacies–the powerful but poor strategies to present or argue your point of view that aren’t grounded in ethical, reasonable, and real points.

There are dozens, so I will cover the main ones that creep up in technical and professional contexts more. Review these as both warnings against unethical arguments you might make and also to recognize when a source or a person is using them in the information you read.

Ad Hominem is attacking the person instead of the arguments, basically. It is used so OFTEN because it is such low-hanging fruit, but invalidating a position based on irrelevant personal traits instead of the issue at hand just distracts. Similar to ad hominem, a Red Herring actively tries to distract and shift the focus by introducing irrelevant or barely connected points. Don’t let people in an argument or in their writing distract you from the facts and logic of the matter at hand.

Straw Man argues with exaggerated and inaccurate versions of the argument or topic. It is often paired with the Slippery Slope, which claims a more serious or extreme consequence will happen due to the starting point or single event. Try not to let yourself and others build unrealistic, unlikely, and undersupported outcomes with these fallacies. Stick to the documented and reasonable correlations or patterns of events.

✨When we research for our technical writing, it can be easy to fall into a Hasty Generalization or an Appeal to Authority where we make statements and conclusions after just a few examples–that could be outliers or small compared to the bigger picture– or focus too much on the arguers expertise. The Appeal to Authority does state that the expertise is irrelevant or overstated, so… just because I have expertise in technical writing, that doesn’t mean you should take my claims to any old topic. Just the ones actually related to this class AND review the added perspective materials I provide where other authors explain the topics and other examples are used.

✨The last set of appeals that are most relevant to writing situations is the Causal Fallacy, which implies a relationship between things, especially a correlation (so one thing causes the other) when really it might be an association at best. These sometimes show up with Circular Arguments, where the premise becomes the conclusion instead of adding new information and justification. I personally see statements and writing that follows the Casual Fallacy and the Circular writing with our LLM interns. The AI systems have a tendency to try and connect things and repeat the premise of your prompt as evidence. So, really watch out for that.

Again, there are loads of logical fallacies that are applied to more argumentative debate contexts. As technical writers, we don’t often partake in truly persuasive or argument-building situations. Instead, we need to look more at what our research, sources, and overall data may display. When analyzing data, it is possible to accidentally build on or use these fallacies, so stay critical and think through the logic of your work.

Recap

You should have notes on the following areas with examples to help you remember and relate the information to your own life and career.

  • The 6 official ethical principles for technical writing
  • The single big-picture ethics to act on in your careers
  • The legal obligations for protecting consumers
  • The difference in liability and warranty
  • How to protect yourself from copyright issues
  • What consequences can happen with digital accessibility requirements
  • 8 logical fallacies that are more common for technical writing

 

Conclusion

We’ve reached the end of this lecture on Introduction to Technical Writing! Please look over your notes as we review the key areas you should have definitions, examples, and applications. You can play this podcast back and reference the transcript/book chapter.

 

✨Technical Writing as a Discipline

  • Technical writing is different from essay writing. It is reader-focused and action-oriented, and it is formatted to be easily scanned.
  • Technical writing can include print, digital, interactive, and audio/visual material.
  • The key characteristics of technical writing are that it is useful, usable, and enjoyable.
  • A good visual strategy is important for technical writing. Key principles include contrast, repetition, alignment, proximity, and size.

✨Styles of Technical Writing

  • There are four main ways to present information in technical writing: scholarly, functional, interpretive, and affective.
  • Scholarly writing is theoretical and academic, and it is intended for expert-level readers.
  • Functional writing is practical and jargon-heavy, and it is intended for practitioners.
  • Interpretive writing explains concepts in general terms, and it is intended for non-experts.
  • Affective writing focuses on sharing an experience and connecting with the audience.
  • The style of writing should be chosen based on the audience and the purpose of the document.
  • There are six main genres of technical writing: correspondence, documentation, end-user materials, analytical reports, strategic reports, and media.

✨Ethics in Technical Writing

  • Technical writers have an ethical obligation to not mislead readers.
  • Information should be presented in a way that is accurate, complete, and unbiased.
  • Writers should avoid plagiarism and copyright infringement.
  • Digital accessibility is a key ethical consideration for technical writers.
  • Writers should be aware of common logical fallacies and avoid using them in their work.

We made it through this lecture on Technical Writing at large and as an introduction. Good work and thanks, associates.

Vibes.

Cartoon Professor HB smiling and waving Okay, BYEEE!

 

Credits and Sourcing

Information and content in this lecture is derived from a combination of the following sources and the creator–my–personal experiences in education, technical environments, and professional roles. This content is licensed under the Creative Commons Attribution-NonCommercial-Share Alike, so you are free and encouraged to distribute and remix any part in any new medium for your goals. Please ensure your creations are available under the same license to keep the information spreading.


Chapter 1: Introduction to Technical Writing. Copyright 2019 by Mike Markel and Stuart A. Selber in Practical Strategies for Technical Communication. Published by Bedford St. Martin’s.

Technical and Professional Writing Genres. Copyright 2019 licensed under a CC: BY, NC, SA. By Michael Beilfuss; Staci Bettes; and Katrina Peterson. https://open.library.okstate.edu/technicalandprofessionalwriting/front-matter/158/

Technical Writing Essentials Copyright © by Suzan Last and UNH College of Professional Studies Online is licensed under a Creative Commons Attribution

Acknowledgements

 

License

Icon for the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License

Technical Writing and Presentation Copyright © 2024 by Hayley Blackburn is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License, except where otherwise noted.