cdmandrews.github.io
Notes and Overview for Week 6
We are continuing our focus on elements of technical communication this week, with a particular focus on structure and style. Structure is the overall organization or shape of your ideas; unlike in lots of school-type writing, technical and professional writers use things like headings, lists, and summaries to reveal the structure of a document for readers Style is the way you express your ideas in a document, from the paragraph level to sentence structure and the words and phrases you use. Style is different from correctness, which has to do with squeaky-clean grammar, mechanics, and spelling. As your reading this week will point out, style guidelines (such as the 7Cs) can conflict with each other, and there are always tradeoffs. As a writer, you need to be able to begin noticing structural conventions and writing styles when you see them and make decisions about when to use a them or not.
You also are working on your fact sheets this week, and we will have our first peer review session for those. You’ll need a rough draft of your fact sheet about writing in your profession for project 1 ready by Thursday. More details on that below.
Assigned to read this week
- BLUF: The military standard that can make your writing more powerful Bottom-line up front, aka Conclusions-first is a powerful approach for many kinds of professional writing.
- The bite, the snack, and the meal is an approach to web content writing that you will find useful more broadly in your professional writing, as it emphasizes making your key message clear in three “sizes.”
- Effective rhetoric, effective writing: Parallelism in technical communication introduces parallelism at the sentence level.
- Subheadings: Perhaps the most useful technique in technical writing is an excellent article about subheadings that also actually practices what it preaches.
- OTC Chapter 4.4: Headings
- OTC Chapter 4.5: Bulleted and Numbered Lists
Findability: Emphasize your key messages
Whenever you communicate, whether you’re informing, persuading, or entertaining, you convey information. Making sure to convey information in a way that meets audience needs is the central practice in technical communication. In week 02 we identified ways technical and professional writers make purposes explicit in texts. In week 03 we conceptualized TPW as a rhetorical, situational, ecological set of practices. In week 04 we looked about how we can use document design to orient readers and help them find information. Last week you looked at writing with a “you-attiude” and creating reader-centered messages. This week, we’ll look at highlighting and reinforcing key information, or key messages in your content.
As you’ll remember from the introduction to document design, technical writers make use of several typical design features to enhance readability and make it easy for readers to find information they’re looking for. These include headings, lists, figures, and tables, as well as strategic use of passive space around all of these features and text. The readings for today offer details and examples of how and why technical writers use the following document design features:
- Starting summaries: use summaries, topic sentences, and “beginnings of sections” more generally as a space to orient readers to your key messages and help orient them to the text. BLUF and Bite, Snack, Meal are two useful approaches for doing so.
- Headings: headings and subheadings provide a clearly visible organization and structure that allows readers to read selectively and preview information. There are several guidelines for font style, size and color to help design headings effectively.
- Lists: lists provide a way to concisely and efficiently convey information and emphasize ideas. There are several kinds of lists, each used for specific purposes. You’re probably familiar with numbered and bulleted lists; you’ll also read about in-sentence lists, two-column lists, lists with run-in headings, and nested lists.
Two useful approaches to writing: BLUF and Bite, Snack, Meal:
BLUF, or Bottom Line Up Front is harder to get right than it seems from the name, because it asks writers to balance two competing needs: concision and completeness. Beginning technical writers often mistake concision for shortness, but they’re not the same thing. Concise writing is not just using fewer words–it’s about conveying precise meanings without extra filler. BLUF does not mean “try to shove the whole thing in a single sentence;” instead, it’s about starting a message by clarifying the most important information, reinforcing that importance visually (perhaps by putting it in its own paragraph or using document design techniques to highlight it), adding the important context to help readers understand why they should read, and then proceeding with supporting details and information. This works at all scales: from text messages to emails, from single-page memos to 172-page reports. (But mostly read that article!)
Bite, snack, meal is an approach borrowed from web content writing that emphasizes making your key message clear and accessible to skimmers and deep readers at the same time by reproducing key messages at three levels:
- the bite: a headline (or title, or subheadings) with a message
- the snack: a concise summary
- the meal: the full details of the content
To be able to do this well as a writer, you really have to have a sense of what your key messages, big ideas, and major purposes are. You also need to have an idea of what your audience needs, expects, and values. This is all part of the planning phase of your writing process. You need to be able to accommodate readers that:
- want the right information at the right time at the right level of detail
- have a finite capacity to process information
- have a finite attention span and patience
Technical writing isn’t like night-before-it’s-due writing for your history or psychology (or yes, English) classes. Often student writers find themselves inventing content for their essay as they write the first (er, maybe the final!) draft. That’s what I call writing your way into it—you probably know the feeling, where you sit down and look at a blank page and an assignment and have no earthly idea about what to write, so you just kind of start and see what happens. Eventually, a main point arrives, and that’s the thing you write about in your conclusion. But it’s not necessarily an idea you had at the beginning. That’s okay as part of your process, of course—writing is an inventional process of embodying and constructing knowledge. One way we come up with ideas is by writing them down and seeing what they look like, and then adjusting them along the way. But often the texts that come out of that inventional process (Anne Lamott calls them “shitty first drafts”) aren’t meant for human consumption. They can’t be the last draft. It’s your job as a writer to then come back, revise it, refine it, and figure out what the heck you really want to talk about in the first place.
Information development isn’t a one-step process. It’s a recursive, circular process where you’re continually backing up and revisiting old steps and moving forward to new ones. It’s only once you really know what the bottom line is that you’re able to put the bottom line up front in your writing. Just because the conclusion gets put first doesn’t mean that the conclusion is the first thing you should write!
When you plan your writing; put summaries, overviews, and conclusions at the beginning of texts; and use titles (or subject lines) and subheadings that contain key messages, you are emphasizing your key takeaways and shaping your information such that readers don't miss the point.
The following slideshow includes supporting visuals and notes for bite, snack, meal and inverted paragraphing, as well as key messages and different styles of subheadings:
Use parallelism everywhere
Parallelism is another power technical communication skill. Parallelism is balance in structure between multiple elements, especially words, phrases, and clauses. By using parallel grammatical forms in headings, lists, and sentences, you line up related ideas and help your readers follow what you’ve written and create a mental model of it (especially in the case of larger structures like headings and subheadings). Use parallelism to create expectations in the audience about the format of information.
The following slide show works through a number of examples of three kinds of parallelism:
- conceputal parallelism
- grammatical parallelism
- format parallelism
Balance your 7cs
The 7Cs of communication are principles for “good technical and professional writing.” They have come up in our readings a few times, but I haven’t done much editorializing about them yet. This short article overviews some of the complications related to navigating the 7Cs as a real, live, human being.
The 7Cs are a useful short checklist of qualities effective communication ought to have. Good technical writing is:
For Tuesday
Participate in the "2.5: Findability" discussion thread in your group before 5:00 pm on Tuesday.
For this discussion thread, post 2-3 questions you have about the material for this week. Key topics you read about:
- The BLUF or “Bottom Line Up Front” approach to writing
- The “Bite, Snack, Meal” approach to writing
- Key messages
- Headings and subheadings
- Lists (bulleted and numbered)
- Parallelism
Otherwise, spend this time working on your draft of your fact sheet!
For Thursday
Post a link to your rough draft in of your fact sheet for project 1 in your group’s "2.6: Drafts of your fact sheets" discussion thread before 5:00 pm on Thursday. Use Microsoft Word and your university OneDrive or Office365 account so you can share a link to your document that I and the other folx in your group can easily look at and comment on it!
This draft will most likely be a shitty first draft for you, and that is okay. Whatever it is, share it with us! The only way to do this wrong is to skip it entirely or turn in a blank document.
-
The best practice here is to get organized within your groups and make sure that everyone has at least two people to read their drafts–that way all the feedback doesn’t go to two people. Please use your group email, discussions, or whatever group chats you’ve set up to facilitate that.
-
Use the comments function in Word to provide feedback for at least two of the people in your group.
-
Read each others’ fact sheets carefully and generously. Each time you review you should provide at least two actionable comments to each writer on any or all of the following areas:
- Writing style (how effectively are the writer’s sentences, paragraphs, lists, and words explaining their content?)
- Page design (how effective is the writer’s use of white space, overall page alignment, use of color, CRAP principles, and other aspects of page design?)
- Visual elements (Howe effective, appropriate, and rhetorical are visual elements?)
A few things to remember about feedback:
- It’s a draft and we’re all learning. Be kind.
- Everyone’s learning at different speeds. Be polite.
- It’s still a freaking pandemic outside. Be generous.
- Take the opportunity to learn from what others are doing. Be attentive.
- Give feedback to others as you would have feedback given to you.
- Give writers specific feedback about particular things. This sentence, this word, this picture, this color. Telling writers “It’s great you just have to finish” isn’t helpful–they know that already. Offer specific ideas about how and what to revise or finish.
Peer review is an opportunity to share, learn, and improve your writing. Not participating hurts your final product and the final products of others. Do your group a solid and be present for peer review!! If you do not post feedback to at least two people in your group, you cannot get full credit for peer review activities, even if you posted a draft on time.
Looking ahead
During Week 7 we will introduce a variety of issues surrounding figures, tables, and visuals in your technical writing. We’ll also have another round of peer review.