Skip to content

Discussing the first half of the “Tech Writing Handbook”

by Steve Krause on October 12th, 2014

This is where we’ll discuss chapters 0 through 4 of the “Tech Writing Handbook,” which is a free handbook/guide to writing instructions by Kyle Wiens and Julia Bluff from the site iFixit and sponsored by Dozuki, which, as far as I can tell, is a spin-off company that does documentation for larger companies. This is a new reading for me and for this class, and because I’m assigning it, I obviously think it’s useful. The one objection I have to it that I want to get out there right away is  I don’t like the title at all. It should be called something like “Instruction Manual Handbook” because “Tech Writing” is a much bigger and broader category than just writing manuals. But with that out of the way, I think this is a pretty useful reading to think about as you begin to think about your instruction writing.

 

I think this is pretty straight-forward and well-written, so for the most part, I want to hear what you have to say about this in the comments. A few things that I thought were useful:

  • Writing instructions is really a form of teaching. Maybe that’s obvious, but I’ve read a lot of instructions where that didn’t seem to be the assumption at all.
  • “Know thy product,” and remember, part of this assignment is about learning how to do one of the three tasks that are in the options here. You might not be able to talk to the Google experts, but there are some good support documents out there and of course, I’m here to help too.
  • As chapter two makes clear, effective instructions use as few words as possible, a writing skill that is actually a lot harder than you might think. The examples in this chapter are pretty handy, too.
  • In chapter 3, they talk a bit about something called a “hallway usability test.” That’s good advice, and we will be talking more about usability tests later on this week, too.
  • A lot of the chapter on style is actually about humor. My advice here would be to use with caution. I think you can ben fairly informal/user-friendly in your instructions for this assignment, but the problem with humor is a lot of people aren’t as funny as they think they are and it often falls flat. So sure, be informal, but be careful about being funny.

From → Uncategorized

31 Comments
  1. Nijea Wilson permalink

    The first chapter talks about having to know thy product and process; and talking to the experts. I know writing instructions doesn’t seem that difficult but having to write instructions on the topics we were given (which I know absolutely nothing about) kind of makes me nervous. I guess I’ll be repeatedly going through the steps myself to fully understand before trying to write instructions for someone else.

    I think it was interesting that the handbook mentioned that you need to stay concise because most people scan through a text to find information that they feel may be important (I honestly was scanning through the handbook to myself). The important information should be put at the beginning, use as little words as possible to get across what you want to say, don’t throw in a bunch of unnecessary words and make your instructions very clear. Chapter 4 talks about different styles. I think I’m one of those people that think I’m funnier than what I really am while writing, so I try to stay away from putting humor in anything. Another thing that I’m really bad at is using “you” in a sentence when it shouldn’t probably be used. An example given in the hand book was “Be careful when you pull the wire from its connector” vs “The wire should be pulled from the connector carefully”.

    There was a lot of helpful information in this handbook and will definitely be referencing back to it when it comes time to start writing my instructions for this assignment.

    • Brian Gardner permalink

      The handbook was insightful for sure. I’m so used to writing papers and stories that I tend to spice up sentences with interesting wording, but instructions are about efficiently producing information as opposed to provoking thought or interest.

      Since I’ve rarely had to write manuals before, this handbook was very helpful sparking my imagination about how to tackle this. I don’t have the best reading comprehension so I’m sure I could write near perfect manuals if I had an identical twin to proofread.

      • Jessica Kane permalink

        I also tend to spice up my papers and use words like “fairly” often. I can see how these wishy-washy terms could be distracting from the point and unnecessary.

    • Natasha Wickenheiser permalink

      I do think it is interesting that chapter 2 (I think) stresses the importance of keeping things concise and only including relevant information. On the other hand, chapter 4 emphasizes the importance of keeping things engaging, which often requires something other than including just the facts users need to know. These two ideas seem contradictory; however, I think there is something to be said about having a good balance of the two.

      • Jessica Kane permalink

        Good point. I can see where both would be important. You don’t want to be to wordy but you also don’t want to bore your readers to death.

      • Nijea Wilson permalink

        Yes I definitely agree that it seems contradictory but I give a lot of props to people that know how to balance both topics to make something be engaging and clear at the same time.

    • Steve Krause permalink

      The use of “you” is one of those important little stylistic things that kind of throws some students for a loop, at least initially. But it’s quite useful for instructions, and it is one of the things that makes this kind of writing different from academic writing, too.

    • Melanie Waller permalink

      I agree, it’s hard to try and write in the second, third or fourth person. Sometimes what sounds good to me doesn’t sound good to another.

  2. Natasha Wickenheiser permalink

    I really enjoyed the readings. I also want to pass it on to my technical writing professor, since we have been discussing a lot of these concepts in class.

    In chapter 1, I thought it was interesting that the text stressed the importance of the writing process being an interaction. Tech writers create drafts, and engineers tear them apart and give suggestions for improvement. I think it is important to remember that the writing process tends to run more smoothly if writers engage in continual discussion with the experts and/or the people who will be using a piece of their writing.

    I’m also glad the writer brought up “articles are not the enemy” in chapter 3. When reading more “technical” documents like manuals or instructions, I have noticed that writers often leave out the articles. It never made sense to me. I’m glad that this handbook stresses the importance of using articles where they belong.

    Finally, I liked that chapter 4 discussed knowing when to break the “rules.” As we’ve already talked about in class, there are all these imaginary writing rules that we are supposed to follow. Some do tend to help make writing more cohesive, and some are just preferences. It’s important to remember that technical documents do not have to be strictly mechanical. They can–and should–be engaging, too.

    • LeeAnne Baumdraher permalink

      I’d be interested to know what your tech prof says. Is it Benninghoff?

  3. Carly permalink

    Writing in this style is such a breath of fresh air compared to the essays we hammer out on the daily in college. Particularly, where they explain the concept of dumping empty words, this quote stood out. “The backhoe manual used the phrase ‘In the event of. But ‘in the event of’ is just a fancy way of saying ‘if.’ Why use four words when one will do?”

    It’s so foreign to do these things in a college course, when in most English courses, word count is everything, and writing wordy is expected to a certain degree.

    But actually, I think the things this handbook hits on would improve essay writing too. Eliminating “to be” verbs, passiveness in writing, jargon (in contexts outside say a research paper), and informality, all seems like very good advice in any situation.

    I really enjoyed this read.

  4. Kourtney Lovett permalink

    Being that I have never written serious instructions for serious readers before, I found this manual to be quite helpful. While I can appreciate all 4 chapters, I must say that I learned the most from chapter 2. Completing assignments for this class such as the personal statement and email assignment, have taught me that I am extremely wordy. Over time, I think I’ve gotten used to “flowery” essentially more wordy writing. Chapter 2 really showed me how I can work on condensing my writing not only for the instructions assignments but also for assignments that I will likely encounter in the future.

    • Latasha Davis permalink

      I agree with you Kourtney, I too think that chapter 2 was very useful. Using the correct usage of word language is essential when writing instructions. I also feel that Ive learned a lot from chapter 2 as well as through this course critiquing the way I use words that are meaningful let straight to the point to be more direct. I think that its is a very important chapter and it did a great job explaining it.

  5. Melanie Waller permalink

    I learned a lot from reading these chapters. I like to have short and precise directions. If there are too many words in a sentence, I have to reread it many times and slowly to try and figure out just what is exactly being said. I have never done an assignment like this, so it will be a big learning experience for me. If I skim through things, like I do, then writing instructions will be a challenge. Patience

    • Nijea Wilson permalink

      I would have to agree that if I’m trying to put something together and its just a jumble of unnecessary words I get way to frustrated and have to keep repeatedly looking over the directions to try to understand them.

    • LeeAnne Baumdraher permalink

      Short and precise is definitely the way to go! I seldom read directions, when it comes to assembly, so the shorter the sweeter. Also, PICTURES!!

      • Steve Krause permalink

        The other thing about instructions (and I think they’re talking about this here, too) is because people often don’t begin reading them but instead use them as a reference tool later, you have to keep in mind a reader who is potentially coming at this document to look something up. Again, it gets at that interesting territory of writing something to be used rather than read.

  6. Kristen Smith permalink

    I really enjoyed reading the first few chapters of the “Tech Writing Handbook” and found it extremely helpful. I feel that the advice given throughout these chapters is great for writing instructions, but I also feel that much of what was said could be applied to various types of writing. Some of personal takeaways were the ideas of being concise and eliminating “wishy-washy” words. I know that I tend to have long, run-on sentences and I’m always saying things like “kind of”. Overall, I really enjoy this read and feel that the friendly, informal tone makes it both easier to read, but also makes me feel more apt to take the advice. This is a piece I can see myself going to for advice on all different writing projects.

    • Leah permalink

      Ditto,

      The first few chapter really helped me on how to prepare for this assignment. At first, I was short of confused on what object I would pick and how I would go about explaining it.

      Whew!

      Thank God that Professor Krause introduced “The Writing Handbook”, being that it really went into details on how to do so. I also agree with you on how “The Writing Handbook” could be used for other types of wiring as well.

    • Chelsea Idzior permalink

      I completely agree with you. While reading these guidelines, I was thinking about how I could apply them to my writing overall, and about some of the rules I violate. I am notorious for using unnecessary passive voice and for using too many “to be” verbs. I will have to focus in on these issues when writing my instructions.

  7. Latasha Davis permalink

    The “Tech Writing Handbook” Chapter 0-4 is good reading tools to create a great instruction manual. When you are writing a manual it important like they suggested to ” look before you write”. You want to have previous experience about the particular things you want to instruct to do. In chapter 1 they did a great job explaining that rule. In chapter 2, the writer talked about being concise and straight to the point. Sometimes we tend to write to much. Thats not important or even needed when writing a instruction. By being straight to the point the reader is being aware of every direction an make it easier for them to understand. In chapter 3 being crystal clear is also important. You need to be persist so that it doesn’t become a letter has more then enough detail. We as readers tend skim through instructions hat have to much writing and in the end it done wrong. In the last chapter they talked about rule. Rule are important and in they can be changed to meet the need of each writer for the reader. I think these were great chapter and have given be great way to write instruction better.

    • Nijea Wilson permalink

      I didn’t even notice that I will thoroughly read something if its short but skim through it if its to long until I read the handbook lol. I have an extremely short attention span, so short and clear is always better for me.

      • Latasha Davis permalink

        Thats was a good thing to point out. I really agree what the article said about if its too much information most people won’t do it correct. I agree with that statement because i’ve done that so many times. I glad someone else pointed that out because I think its important.

  8. Leah permalink

    In Chapter 1 they bring up two great points in regards to beginning your instruction assignment. One great point introduced was that “You can’t teach someone how to do something until you’ve done it yourself”, which is desperately true. This point gives great awareness stating that before choosing what your instruction assignment will be, you will have to spent some time on perfecting that object yourself, first.
    The Second great point introduces that “If your not an expert at what your writing about, talk to someone who is”, which will give you a better understanding. These two points really gave me great insight on how to go about choosing an object.
    Chapters 2,3, and 4 all have phenomenal explanations on do’s and do not’s. The chapters also states thoroughly ways to start and finishing your instruction assignment. The “Tech Writing Handbook” will be my best friend throughout this assignment, providing very useful information.

    • Chelsea Idzior permalink

      I think that the point about having to do something yourself before teaching others is vital. In high school speech class we had a demonstration speech, which was essentially an instructions assignment, and it was painfully obvious when people didn’t really know what they were doing but just picked a random topic for the assignment. My point here is that if you are not well-versed on the topic of your instructions, and don’t really know what you are talking about, it will show through.

      • LeeAnne Baumdraher permalink

        Oh my gosh, yes! The blind leading the blind is not a pretty sight.

      • Leah permalink

        Oh my gosh! This is so true.

  9. Chelsea Idzior permalink

    After reading the first 4 chapters, I definitely agree that this literature is titled poorly. However, like Professor Krause said, it is useful for our purposes. I am not familiar with writing instructions, especially on a topic that I am not well-versed in, so it will be helpful to have a guideline. Some of the points that really stuck out to me were that writing instructions today is not just simply listing the instructions. The writer made a good point that we should include pictures or other multi-media features because they will be expected due to today’s technological advances.

    I also like the idea of talking to an expert or having an expert review your work. It is like a peer review session from the ultimate peer reviewer. Another point, which I think is well-known to many people at this point, is to keep things concise. Especially with instructions, no one wants to have to sift through 80 pages of paragraph-style reading when they are trying to follow instructions. It is annoying and overwhelming, and would likely lead to abandonment of the instructions altogether.

  10. LeeAnne Baumdraher permalink

    I worked on the Standard Operating Procedures for a telecommunication company for some time, and I learned a lot about tech writing. For one: don’t assume anything. Start very basic, pretend the person who will read your instructions knows zilch. That’s why I like the handbook’s chapter on being “Crystal Clear.” Because it’s probably the most important advice you can get.

  11. Ashleigh Swinehart permalink

    As I mentioned before, I like following instructions that have at least 5-7 steps, maybe even 10, but over that and I feel like there is too much going on. I want to get right to the project or whatever I am working on and don’t want a million steps to read in order to reach my goal. However, I do understand how, like LeeAnne said, that one needs to assume the reader knows nothing and basically needs to have their hands held through the entire process. It all comes down to the individual person and how well they are at deducing from a set amount information.

Leave a Reply

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

Subscribe to this comment feed via RSS