Job Discussion Forums

AsiaTraveller · Posted: Fri Sep 24, 2004 5:20 am Post subject:

kimo,

I just checked the passage you cited on the Internet. You misrepresented it. The author is not �explaining some of his code�.

And by omitting the original fonts from your quoted excerpt, you yourself have introduced errors.

So I ask again:Why are you so presumptuous as to give kitegirl a �quiz�?

Ludwig · Posted: Fri Sep 24, 2004 5:42 am Post subject:

Kitegirl · Joined: 02 Jan 2004 Posts: 101 Location: Lugdunum Batavorum

GLenski and Moonraven - guilty as charged. Yes, perhaps it was the Little Miss Muffet aproach, but that was perhaps because I was trying to come across as friendly - the subtlities of spoken communication seem to be lost on the keyboard at times, resulting in genuine queries that come across as demanding and rude - something I was hoping to avoid with a little frivolity.
And no, I wasn't very specific in the original posting. I'm more than capable of putting a curriculum together, but I've very little experience in the actual business world and was simply stumped re practical skills.
At the first interview they asked me briefly in what ways I would teach skills and I assumed the second interview would go into the actual teaching more, the first having centered around my general approach and attitude.
Ludwig, I'm sure you're a very nice person, but why don't you go use your wonderful social skills elsewhere. I already felt like crap yesterday when they hinted that they turned down more qualified applicants because they thought I'd fit in well. Made me already wonder if I was up to the task - not wanting to let anyone down.
But then I thought, if you always stuck to what you know, you'd stand still and never learn anything new.
(I still miss China though).

kimo · Joined: 16 Feb 2003 Posts: 668

Thank you, Asia Traveller. You have just proven my point. Many teachers of technical writing jump right into the list of documents you provided in your very informative post earlier. To facilitate writing those documents there is something else which I believe you and others neglected. That was the purpose of my quiz.

Anybody with experience in technical writing could look at the piece and see there are at least three typical mistakes that have nothing to do with fonts and whether or not markup language is code or not. Since you say you are a professional, I am amazed you did not point those basic mistakes out.

1) I should not have to tell you that, generally, technical writers try to avoid the passive voice. They want the actors acting. That is not always possible and not always desirable, but the active voice is considered stronger and less likely to make readers go to sleep. "Columbus discovered America in 1492" is an example. However, if I want to stress America and the year it was discovered (or brought to Europe's attention), I would use the passive, "America was discovered in 1492."

2) In technical writing, nothing happens in the future. Documentation such as that shown exists as a collection of information in the present, not something that will occur in the future. If one must use the future tense, it must be valid. We don't say, "Press the button, and a blue screen will appear." Professionals know this could cause the reader to worry and ask, "When will it appear?" "What happens if it doesn't appear?"

3) The author of that piece also used the word 'flavor'. While you and I may understand what he/she means, others may not, especially non-native speakers of English, of which there are many in the technical fields. Technical writers do not use colloquial expression. Standard English is the norm.

I did not intend to misrepresent anything. The piece I submitted was grabbed on a lark as a good example of the most basic elements I listed above. Technical writing is not that difficult once those points are mastered.

AsiaTraveller, while I don't claim to be any great expert, I have studied technical writing, have done some professional technical writing for a variety of audiences, and have an undergraduate engineering degree from a top U.S. engineering school. Take a look at your mobile phone. If it's a Motorola, my students probably wrote the code for it and the associated documentation. Motorola seems happy with the Documentation Writing my guys have been doing, as do Pitney Bowes, CSG and a few others. I'm happy too.

Now I have a question. Why would I dare dream up such a common term for developers as Documentation Writing?

http://drupal.org/node/1916

So to the fine teacher I know you are, mr. AsiaTraveller, have a good day. And good luck to Kitegirl.

waxwing · Joined: 29 Jun 2003 Posts: 719 Location: China

That was rather interesting.
I'm not at all sure I fully understand your reasoning on points 1 and 2. Having spent 4 years as a software engineer/architect and a couple of years as a nuclear engineer I've probably seen a fair range of the good, bad and ugly in technical writing. I'm not at all sure I fully understand your reasoning on points 1 and 2. For example, why is the future tense so evil? In the example you give it seems to indicate a causal relationship (it's a kind of disguised 1st conditional) - and most technical documentation is used to describe causal processes. The audience of this document is clearly a technical one ('deprecate' wouldn't be correctly understood otherwise).

Just interested, don't feel the need to explain in detail if you don't want to.

I'd love to teach technical English and make use of my skills in this area. Any tips on how to get into this field?

Stephen Jones · Joined: 21 Feb 2003 Posts: 4124

Dear Kimo

May I suggest that you don't have the least idea what you are talking about. The passage you quote is perfectly clear, and will be understood by anybody dealing with web graphic software.

The term "is deprecated" is a specialized term in web design (it means the feature will still be supported and will still work, but should no longer be used - and note the use of the future just then).

One could argue with "flavors" but the documentation was almost certainly written by the programmer, and these kind of notes are meant for the technically savvy anyway.

kimo · Joined: 16 Feb 2003 Posts: 668

Waxwing noted:

moonraven · Joined: 24 Mar 2004 Posts: 3094

Save the wear and tear on your keyboard, Kimo. SJ is not interested in reading anything. He is interested in insulting people he feels threatened by or envious of.

Aramas · Posted: Fri Sep 24, 2004 5:10 pm Post subject:

I would be surprised if anyone without an engineering background can adequately teach technical English to engineers. If you can't understand the literature then how can you teach others to do so?

You're going to need to do a lot of research.

Kitegirl · Joined: 02 Jan 2004 Posts: 101 Location: Lugdunum Batavorum

Agreed Aramas. However I've found out I'm to improve their English skills so that when confronted with business contacts from outside the country, they can communicate more successfully. I shan't be teaching tech. vocab really, more skills relevant to writing reports, describing processes and dev'ts, discussing etc.

waxwing · Joined: 29 Jun 2003 Posts: 719 Location: China

Stephen Jones · Joined: 21 Feb 2003 Posts: 4124

AsiaTraveller · Posted: Fri Sep 24, 2004 9:59 pm Post subject:

kimo,

You know some very nice generalizations about technical writing. But they are only generalizations. Other posters correctly warn you about applying them to all cases.

So you are wrong about future tense in this particular example. Actually, you've already contradicted yourself. You first said that "nothing happens in the future" in tech writing. Then you go against your own quoted guideline by saying that �if the author is writing about experiments or activities yet to come, future tense is appropriate.� The writer in your example is very careful to note that the action can only take place in the future. How? By saying that �we plan to change�� In other words, �we� haven't yet done it! Evidently, DocBook version 4.1.2 is still being modified. This is the very type of context in which future tense is used in technical writing. Here's a list of guidelines from one of my presentations for tech writers:

� There is very rarely a need for future tense (for example, sentences with will) in XYZ documents.
� Use present tense to indicate the next step or action, the result of an action, or a continuing or repeating event.
� Use present tense in instructions and procedures.
� Present tense describes actions that are routine, always take place, or are expected to take place (even in the future).
� Use future tense only where necessary (for example, if you know that something will happen only in an updated version or subsequent release).

Furthermore, the writer in your example once again correctly uses the future in his online guidelines:

"graphic. has been deprecated and will be removed as of DocBook 5.x. To prepare for this, start using mediaobject."

However, this whole discussion is moot. The OP (kitegirl) will be teaching engineers, not writers of software documentation. Your quiz touched on only one small aspect of technical communication. Engineers have far fewer proscriptions on tense than do software doc writers.

About pasive voice, I usually present the following in a slide titled 'When Passive Verbs Are Okay' during presentations to writers of software documentation. Again, these are generally accepted principles in the field:

It is acceptable to use passive verbs in the following situations:
�When the context of the discussion makes it clear that the focus of the sentence should be on the receiver of the action rather than the performer
�When the receiver of the action is more important than the performer
�When the actual performer of the action is unknown or not important to the discussion
�When you want to avoid making an inanimate object the performer of the action

So your original quiz passage did indeed reflect an acceptable use of passive. Doc writers shouldn't have to write "We have deprecated..." What if they didn't do the deprecating??? It's not at all important to know who or what did the deprecating. Result: Passive is fine and, actually, more appropriate.

Writers seem to breathe a sigh of relief when they hear this. They have read the same warnings that you give, so they believe that passive is always wrong.

kimo, are you a member of the Society for Technical Communication? I suggest that you become active, attend meetings and seminars, and read the various publications. There's a lot about the field that you don't know!

AsiaTraveller · Posted: Fri Sep 24, 2004 10:12 pm Post subject:

The verb deprecate is common in software-related writing (and speaking). Depending on the audience, it is frequently acceptable. As I mentioned in the preceding post, nobody seems to want to take credit for deprecating something, so it is usually passive! Smile

I'm always encountering words that I think are simply arbitrary neologisms, but then I find that most members of an audience do indeed understand and use them. Case in point: the verb passivate (used in contrast with activate). When I (rather sarcastically) queried the writer, she told me its meaning and gave me examples from our other documentation. For the specific audience in question, we decided that it was fine. (In other contexts, it would not have been fine.) And I learned a new term.

ESL teachers should teach students in Technical Writing classes how real-world tech writers actually work on the job. It would clear up a lot of confusion. You can't learn about this field only from books.

AsiaTraveller · Posted: Fri Sep 24, 2004 10:44 pm Post subject:

From dictionary definitions:

deprecated: Used typically in reference to a computer language to mean a command or statement in the language that is going to be made invalid or obsolete in future versions.

deprecated: In computer programming, a deprecated language entity is one that is tolerated or supported but not recommended. For example, a number of elements and attributes are deprecated in HTML 4.0, meaning that other means of accomplishing the task are preferred. Deprecated features may become obsolete in future versions of HTML, though browsers that support the features may continue to support them. In the Java programming language, a particular method may be deprecated for a given class of objects.

And here�s a nice discussion of the history of the term:
http://www.worldwidewords.org/topicalwords/tw-dep1.htm