Skip to content

Discussing the Second Half of the Tech Writing Handbook

by Steve Krause on October 14th, 2014

Here we’ll continue with the Tech Writing Handbook, from chapter 5 to the end. I think you’ll all agree this is pretty straight-forward stuff that doesn’t need a lot of explanation from me, so I’ll again just hit a couple highlights and wait for all of you to jump in.

 

A few highlights I noticed:

  • Chapter 5 on knowing your audience is of course reminding us of a common theme for all of the writing in this class. But definitely a worthwhile reminder.
  • I would recommend taking the Flesch-Kincaid Readability Tests with a grain of salt, and even their example here should make one pause. I have a hard time believing that Macbeth is an “easier” read than the Apple Pro computer model.
  • For our purposes and instructions, the chapter on photography is probably not that useful. But you will want to include pictures for your instructions!  It’s just that you should probably do them in the form of screen captures on your computer.  The same is largely true with the advice in chapter seven on diagrams and videos. I have thought about making this assignment one where you are supposed to make a video, but for the time-being, it’s text and pictures (or diagrams, if that makes sense for you). But again, the advice here is useful potentially for other projects.
  • Chapter eight on organization is handy because that too is key in instructions– make sure you are telling people to do things in the right order, for example.
  • Chapters nine and ten aren’t that key for our purposes here because we’re not really that concerned about the legal implications of our instructions (which is one reason why working within the confines of Google docs is probably a better idea than asking you all to create instructions for something that could cause injury), and you don’t have a lot of choice in publishing for this assignment. Though remember: for this assignment you can use Google docs to put together your instructions, or you can use some other software and present your instructions as a PDF.
  • I’m glad they end this with chapter 11 and emphasize the need to edit and to test your instructions with users. Very true.
  • And again, the appendix here is interesting but probably not that important for our purposes.

Okay, so what do you think?

From → Uncategorized

32 Comments
  1. Natasha Wickenheiser permalink

    I think I enjoyed the first few chapters better than this section. This series of chapters presents nice reminders about some of the core writing ideas (writing for an audience and editing); however, as already mentioned some of the content was irrelevant to what we will be doing in class.

    I did like that the text stressed the importance of usability tests. Too often, we assume that what we write makes perfect sense, but we have to remember that every single user is coming from a different background with different skill sets. As writers, we are responsible for meeting those users at their level, and guiding them so that they can properly follow our instructions. One way to achieve this is to avoid jargon, but testing a set of instructions with an actual audience will give significant insight in to how a draft needs to be revised.

    One other thing that I appreciated from this text was a note from the photography section. I had never thought about it before, but it makes absolute sense for a photo to capture a step from the user’s point of view. This should be easy for our project, since we can use screenshots, but it is important to remember for other types of instructions we do later in our careers.

    • Jessica Kane permalink

      For the most part, I agree about the usability tests and meeting them at their level. I guess I would have to wonder what skill set it is that we are currently expecting our users to start. For example, if we were to give these instructions to our great-grandmother, would we expect them to already have a Google account? If not, would you want to include this in your directions or refer to another piece of documentation (intelligent content reuse – Chpt. 8)? Or, if you are writing this for a second-grader, would you want to make the font different in some way on key words and concepts? Although this won’t be a problem in this assignment as our parameters for target audience are set, I think you might find something that would resonate with the entire spectrum of potential users if you’re thinking about something that would work for the extremes.

    • Melanie Waller permalink

      I like you enjoyed the first few chapters. I was trying to take notes to help me remember what was being said and I ended up with 3 pages. Guess I need to cut all this down to about a page and a half.

    • Brian Gardner permalink

      I think the second part was redundant and empty for the most part. The part about using videos was kind of interesting, since I haven’t thought about how videos aren’t easy to skim (maybe better with a table of contents). The rest of it seemed to become what I thought they said not to make – drawn out and repetitive.

      I was reading about the usability tests out of curiosity, they seem useful. Weird to relate this to finance/accounting, but it reminds me of ratios we look at – they’re useful metrics for quick tests. I assume they aren’t used alone but sentence and syllable length is a good way to determine readability.

  2. LeeAnne Baumdraher permalink

    Does it bother anyone else that the Tech Writing Handbook is being a bit too familiar with the reader? It’s like they’re talking to me as a buddy ol’ pal, and I’m not 100% comfortable with that. One of the chapters is about audience, and I think they might have forgotten to read their own chapter.

    And as I’ve said many times before, pictures/diagrams/videos are important. So, I’m glad they added a chapter on that.

    • Nijea Wilson permalink

      Lol, you make a good point. I do agree that pictures, diagrams and videos are important. I actually would much rather watch a video or a diagram then to have to read instructions.

    • Kristen Smith permalink

      I also agree that pictures/diagrams/videos are a nice touch to instructions. At times I also felt that the writing went a little too far in the informality, although overall I enjoyed the informal tone. I feel like they were trying to make their writing easy and fun to read, but at times it almost felt a little silly.

      • Brian Gardner permalink

        I couldn’t think of trying to read my way to quick instructions, I need the little diagrams and pictures to understand instructions. Guess it’s good I live in a day and age where pictures and videos are easily available.

    • Kourtney Lovett permalink

      Personally, the familial tone doesn’t bother me. It actually makes the reading a little more entertaining. I don’t feel like I’m reading dry material that lacks personality. I do understand your perspective though. Sometimes being too informal can come off as a bit disrespectful especially if there is no personal relationship involved.

    • Chelsea Idzior permalink

      Some of the things that they said were funny, but I also think that sometimes it sounded forced. There were some areas where it felt that they really had to try to inject humor, and that rubbed me the wrong way.

      • Steve Krause permalink

        I agree with what all of you are saying here. I think what they are trying to say is you want the “voice” in your instructions to be fitting with your audience and your purpose. There’s a passing example in chapter 4 where they write “If you’re writing maintenance procedures for a nuclear power plant, it’s probably best to stick to a formal, business-like tone. If you’re writing instructions on how to build a backyard barbecue, feel free to write in a style that is friendly and informal.”

        That said, I think they are probably trying to push an approach that is a little too informal. And funny is hard. I’ve read a lot of student essays over the years where the writer tries to be funny on the page and it more often than not falls flat. It’s a lot easier to crack a joke in person than it is in writing.

        So I guess my advice is to think of a voice that you think is fitting for you and for what you’re trying to do here. If I were to equate it to clothes, I’d say business casual: that is, not super dressed up but not jeans and a t-shirt either.

        • Leah permalink

          Umm.. Great point professor Krause on stating that the “voice” has to fit for your audience and purpose.

    • Melanie Waller permalink

      I feel that with this being such a long number of chapters to read and understand, they probably felt they had to try and keep the readers interested and by that they used a little humor. It took me over 3 days to read and comprehend this because I kept drifting off in my thoughts and taking notes so that I could get a better handle on this assignment

    • Leah permalink

      The informal tone doesn’t bother me either Kourtney. I think that by this person being so casual throughout the reading interest me more. I honestly always don’t want to read things that are always formal and professional. I think that is why I enjoyed the free feeling tone of the Tech Writing handout book.

      I do feel that some of the content is forced (jokes) like Chelsea stated, which are kind of weird but hey.

  3. Nijea Wilson permalink

    The manual makes a good point of stating to write at the audiences level “shouldn’t be harder than reading Shakespeare”. Chapters 6 and 7 talk about the most important part to me when reading directions, which is pictures, diagrams illustrations. I have the most difficult time ever if I don’t have a picture to look or a video to look at and be able to rewind to see how steps are completed. Chapter 8 gives a lot of important information in regards to organizing instructions. If you don’t put instructions in a clear order or organization it makes the process of trying to learn something much more difficult. It’s also good to put yourself in the readers place to see if the instructions make sense to you while reading them. As the Professor stated chapters 9 and 10 doesn’t really pertain to this assignment but talks about legal requirements/being safe and publishing. Chapter 11 references the need to always edit. It’s also important to test out your instructions yourself.

    • LeeAnne Baumdraher permalink

      I agree with Professor Krause, though, regarding the Macbeth/Apple Pro comparison. Instructions aren’t always the easiest, but comparing them to the level of Shakespeare is just…a bit out there.

      • Natasha Wickenheiser permalink

        I agree, too. Though, having taken a Shakespeare course, the text becomes much easier and enjoyable when you start to learn the language. I suppose the same could be said about instructions. The big difference is that most people do not have to read Shakespeare to survive in the world or accomplish tasks. They do, however, need to be able to make sense of instruction sets that they are using in their lives. This emphasizes that good instructions are extremely important, and require accurate order, language, and illustrations.

        • Melanie Waller permalink

          When it said that Shakespeare was at the 11th grade reading level, now I understand why we studied it as a Junior in high school. Even though at the time it seemed to be WAY over our heads. Of course, it is hard to read and understand but once you do, the language is beautiful and spoken so graciously.
          I think this goes under the “addressing the audience” section. I just hope that I can write good enough for someone to “Easily” understand what I am trying to accomplish

    • Kristen Smith permalink

      I am the same way with enjoying pictures/diagrams/videos. Even if I fully understand the written instructions, I always appreciate pictures or diagrams being added so I can have the extra assurance that I’ve gotten the written instructions right.

  4. Jessica Kane permalink

    I found these chapters very useful, especially the organization in chapter eight. Having an idea of the time a step should take would be comforting to me as a novice user. That way, if I missed the approximate allotted time for the task, I can question whether I am doing something correctly. I also think it’s a good idea to have the “warning” or “caution” icon next to some of the trickier steps (chpt. 7). I’ll stop and actually read the entire step instead of skim the section for key words when I see these symbols.

  5. Kristen Smith permalink

    As others have said, I enjoyed the first section of this reading more, but found this section to be helpful as well. While it doesn’t necessarily apply to our instructions, I enjoyed the chapters focusing on using pictures, documents, and videos. Personally, I enjoy having the combination of written instructions followed by a picture or diagram that illustrates exactly what I am supposed to be doing. Basically, I like the extra assurance that I’m doing it right. Chapter 5 was interesting and I learned that there are readability tests available in multiple places, which I might have to look in to and start using. Overall, I think this handbook is quite helpful and interesting, even if not all the content applies to our instructions assignment.

  6. Kourtney Lovett permalink

    I really appreciated chapter 6 and 7 which talked about the use of photos and visuals in directions. Being that I am very much so a visual learner, I find the text-photo combination to be extremely helpful. Yes, I can usually understand the text by itself but when I have an idea of what I am doing is supposed to look like, my level of comprehension significantly increases.

    Like Professor Krause, I am appreciate of the fact that they included chapter 11 about editing your instructions at the end. I think it is important to reread what I have came up with so that I can be assured that there are no grammar issues and everything flows. I am also a big fan of reading out loud what I wrote and/or allowing someone else to read it.

    • Chelsea Idzior permalink

      I agree that visuals are extremely important for this assignment. If I look at an instruction manual and see that there are no photographs, I immediately feel irritated because I know that it is going to make the task harder. Sometimes, I barely even read the text and just use the photographs if they are detailed enough.

    • Elyse Cawetzka permalink

      Agreed. In my opinion, no matter how you learn best, visualizing what you are doing can help you. When I am reading instructions on something I know how to do with great confidence and it gives pictures, I always look at them, not necessarily for instruction or guidance but for clarification that I did it correct.

  7. Latasha Davis permalink

    I enjoyed the other half of the “Tech Writing handbook”. In chapter 5, I liked the example of a Audience book; The Dummies Series. I think that these books show a great example of how the targeted audience is used. They also enlighten readers on how reading level is important when writing instruction. “The lower the reading level the more your reader will be able to understand what you are saying” I think that this is important to point out because sometime we don’t think about this concept and it can really cause a issue for readers. Word choice for the intended audience is important. In chapter 6 that talked about Photographing the process. When I first read the title I thought about IKEA. A lot of there items at their store use this type of manual instruction. I think that its a great benefit for the reader. In chapter 7 they talk about diagrams. Having a visual and written instructions are great for readers. It make it easier for the reader. In chapter 8 it discuss organize content. Setting up a manual needs to be organized. It makes it easier for the individual that reads it to understand. Steps are also great ways to guide the reader. In chapter 11, Editing becomes the most important step to making sure your instruction flow. Though editing your own work you can see what works and what doesn’t. It was a great chapter that shared also of insight on writing a manual.

    • Steve Krause permalink

      The other thing about IKEA directions that is very clever is that’s a company that is selling stuff all over the world. But with minimal use of language and these sort of generic “humans” putting stuff together, they can pretty much give their customers the same instructions no matter where they are from/what languages they speak.

  8. Chelsea Idzior permalink

    The parts of the advice here that are applicable to our project are very useful. I like that the writers emphasized the need to consider your audience. You should always keep your audience first and foremost in your mind when writing. A writer could create a really well-written piece, but if it fails to be usable by the target audience then it is not a successful piece of writing.

    One thing that I did not like about the reading was in Chapter 8, which stated: “Outlines are a necessary part of writing. Period.” In one of my other courses we were discussing different people’s styles of writing and how outlines don’t work for some people, just like other forms of prewriting might not be effective for all writers. For this specific assignment, yes, some type of outline would be helpful to give the writer direction. However, I do not think that outlines are a necessary part of writing in general and I never use them. They are ineffective to me and do not help me whatsoever.

  9. Melanie Waller permalink

    Yes this whole section was very helpful. I wrote down a lot of notes to help guide me through the steps. My notes need to be cut down and that will help me (hopefully) get through this assignment. I will probably go back to those chapters many times to make sure that I am doing this right.

  10. Leah permalink

    The informal tone doesn’t bother me either Kourtney. I think that by this person being so casual throughout the reading interest me more. I honestly always don’t want to read things that are always formal and professional. I think that is why I enjoyed the free feeling tone of the Tech Writing handout book.

    I agree strongly with Professor Krause when addressing LeeAnne’s comment.

    I do feel that some of the content is forced (jokes) like Chelsea stated, which are kind of weird but hey.

  11. Carly permalink

    It really is a challenging thing at times to gauge who you’re writing for. It can be very easy to assume a reader knows the meaning of an acronym because YOU think it’s standard knowledge, but that’s really based on the community you’re raised in. A little off topic, but it reminds me of a reading (can’t remember if it was in class or in free time), where it was determined that a test like the reading portion in a ACT-type test was not catered to inner-city students, because it used terms that most of those students had never been exposed to. Just an interesting thought.

    As far as Chapter 6 on Photography goes, I’m relieved that this website points out the difficulty in IKEA manuals. There have been times where I’ve had more luck not using their directions at all. I think it goes a little beyond what we need to know about taking a good picture, but all in all, I enjoyed what they had to say.

    Chapter 8 reminded me of what you mentioned in 354 about organizing our websites by laying out cards in the order of things we thought went together, and then letting someone else organize them based on their thoughts. Wouldn’t be a bad system to implement regularly for these types of things.

  12. Ashleigh Swinehart permalink

    I do like the addition of picture, diagrams, videos, etc., but at the same time, I feel like it clutters the place up and makes it hard to wade through the instructions so that I may find my way out and finish the task at hand.

  13. Justin Trudell permalink

    I thought it was interesting to note the instructions for the MacBook was rated harder to read than Shakespeare. This seems to be the worst possible way to write instructions, making it hard to understand.

    I can totally relate to the section about acronyms being overwhelming. I have been in the marketing field for about two years now and it’s seemingly nothing but acronyms about the business. It gets really confusing.

    The part about diagrams seems like it would help as well. However, from my experience these are TERRIBLE when it comes to neckties. I google how to make specific knots all the time and the pictures do nothing for me. A video is all that will help for me.

    The organization is a key component as well. It was very helpful to mention how making it known the upcoming tasks will be especially difficult before they are attempted. Let the audience know what is ahead of them.

Leave a Reply

Note: XHTML is allowed. Your email address will never be published.

Subscribe to this comment feed via RSS