Summary - Guidelines for Developing Instructions
Team 3 - Bynum & Peterson
Chapter 6 covers the use of both command and non-command verbs in a set of instructions, as well as nomenclature, nouns, pronouns, and the other parts of speech, including punctuation and symbols. Inaba also adds a list of command verb followed by a list of their definitions. Throughout the chapter, Inaba states rules, such as a topic sentence for the following paragraph. These rules cover everything from use in one statement to use in the whole document. Most of the rules are followed by a paragraph, and sometimes an example, which further explains the rule. Most of the rules in the chapter revolve around one basic principle, keep it simple.
Most of this chapter was already common knowledge to myself but I wish I had read it before doing the Quick Start Guide because I'm sure that the guide could have been done better.
(Since I still don't have the textbook, Matt took on the responsibility for writing the entire summary for this week's chapter. - Anne)
Chapter 6 covers the use of both command and non-command verbs in a set of instructions, as well as nomenclature, nouns, pronouns, and the other parts of speech, including punctuation and symbols. Inaba also adds a list of command verb followed by a list of their definitions. Throughout the chapter, Inaba states rules, such as a topic sentence for the following paragraph. These rules cover everything from use in one statement to use in the whole document. Most of the rules are followed by a paragraph, and sometimes an example, which further explains the rule. Most of the rules in the chapter revolve around one basic principle, keep it simple.
Most of this chapter was already common knowledge to myself but I wish I had read it before doing the Quick Start Guide because I'm sure that the guide could have been done better.
(Since I still don't have the textbook, Matt took on the responsibility for writing the entire summary for this week's chapter. - Anne)
posted by Anne Peterson | 3:11 PM
11 Comments:
I have to wonder about how much credence I can put in Inaba's list of command verbs when probably the most common one is omitted - "click". Other common command verbs that are not listed include "browse", " scroll", "launch", "exit", "minimize" and "maximize".
I'm puzzled that a text we are using for an online documentation class ignores the command verbs utilized in software documentation. It concentrates on mechanical and manufacturing technical writing at the expense of computer systems technical writing.
Carl, glad you didn't say "click on." It's my mission in my Federated life to omit that combination. I'm not even sure anymore where I read that "click" was preferable to "click on," but I've taken it to heart. I also try to use the verb "type" instead of the word "enter." I get a lot of documentation from authors with that phrase. If a person has to actually add text, I change the word to type. I like to save enter for the Enter key function. Good points, Carl.
Using the appropriate command verbs is such an important part of documentation. It is also important to consider the command verbs when creating a document that will be translated (like the bilingual FAQ's project we just did). In ENG271, I remember doing a project that involved using a web translator - we were supposed to translate the text into another language, and then use the translations to change the text back into English, in order to see how closely the instructions ended up being to the original. I had used the verb "Hit" instead of "Click" throughout the set of instructions, and this translated back into English as something like "Punch" or "Blow". So I quickly figured out that "Hit" was probably not the right term to use when instructing someone to use the computer mouse to click on a link!
Like Emma said, the correct use of verbs can be vitally important to the documentation that we write. If we use the wrong verb, then the document can sound clunky and will just confuse the reader. This is going into an area that I’ve always struggled with. Going back into elementary, grammar is a subject I have always had difficulty in. I’m not sure why, but it’s just never fully clicked with me. This is very odd considering that I have a Bachelor’s degree in English and am currently going for a Master’s in Tech Comm, yet grammar has made me a bit skittish. I have the feeling that wherever I do find myself in the workplace, it will probably require an editor.
Semantics are important in any field of communication, so it's easy to see why proper verb usage is needed. For instance, in operating machinery, there is a difference between "turning" a dial as opposed to "spinning" it.
I have to both agree and disagree with Carl's comment about Inaba's list of command verbs. It is puzzling that, in an online documentation class, our text omits basic software documentation terms. However, in an increasingly metaphorical environment of software, maybe these words are getting overused. Also, I realize that technical writing is a combination of praxis and techne, meaning there is no one correct way to do things. A book can't say "this will work", but rather "this is what will usually work." So, even though our texts are contextually clashing with each other, there are important points to draw from all of them.
However; there is something to say about conventions. Dodging them could get you in serious trouble, and there are many cases where it would be better to stick with the common-knowledge verbs like 'click'.
Since this chapter was a grammar chapter, perhaps something could have been included regarding the use-or misuse-of reflexive pronouns (such as using "myself" where "me" should be used).
I agree with Carl that the work "click" should be on the list, but I don't expect that this list is necessarily all-inclusive, even though the author would have us believe that it is. I also think Anne makes good points about the use of "type" and "enter."
Will says it best when he states that the books aren't necessarily in agreement with each other, but that we should take away useful information from each of them.
I think that there is an enormous value in keeping things simple. However, I tend to over explain things because I fear that I may omit something and therefore things can get confusing. Using appropriate command verbs without over complicating things is extremely valuable. As Emma mentions, certain verbs or commands may not be translated correctly in to different languages and therefore it's important to note any differences so as not to confuse the reader. I think that anytime a set of instructions is going to be translated it's important to make sure that the translated language has a close equivalent to the original language otherwise, like Emma said, someone may be doing something literally because the equivalent of the original word may mean something totally different.
You are absolutely right. It does seem odd those would be omitted. I haven't had much experience in this area but it does seem as the ones you listed and more common ones are probably missing from this chapter.
This chapter covers a very import part of the content of a document and how it is read and interpreted. As Emma reminds us of just how import in it to keep a document short and simple and to the point while using the precise words to direct the instructions. When I used a web translator for some of my assignments I too had to reuse different words to give better directions.
no book
Post a Comment
<< Home