Thursday, April 08, 2004
Are we talking with programmers or software interfaces?
We have been discussing language and documentation. But who are we in a discussion with? Are we using language (in our documentation) to ease the software user's learning curve with the software interface (the dialog boxes, pull-down menus, navigation bars, and menu bars) OR are we using language to interact with the programmers who wrote the code (in C++, VB, Cold Fusion, or COBOL)? Who are we really talking with?
Tuesday, April 06, 2004
Question for A. Rost
Okay, I'm going to ask the cliche question that always gets asked, because I think it's beneficial: What would you consider to be the most important skill or few skills that a technical writer should have?
I'd have to say that I agree w/ Barker, though I'm a little thrown off by his use of a non-absolute and an absolute in the same sentence, referring to the same thing ("...MANY problems...ALL revolve...") - does he mean that many problems revolve entirely around 2 failures? If so, okay, I agree - many problems can be attributed to those 2 widely-encompassing, very broad issues, which include any number of smaller failures.
From my experience, I'm most irritated by instructions that are written in overly formalized language with a complex structure that doesn't present the information in a clear, concise manner - that is, as Barker states, when instructions don't appear to be written to a "real person."
I've also found that some instructions that are supposed to be written for novices still use language that is, and assume that the user is familiar with terms that are, beyond the novice level - which is pretty much as Barker puts it, a failure to write so the user can easily perform the task.
To me, the instructions that avoid these failures, do, as Nate stated, use active voice, present steps in numbered list format (one step per number), use numbers only for steps, use simple sentence structure, and use terms appropriate for the audience --- and diagrams are good too.
From my experience, I'm most irritated by instructions that are written in overly formalized language with a complex structure that doesn't present the information in a clear, concise manner - that is, as Barker states, when instructions don't appear to be written to a "real person."
I've also found that some instructions that are supposed to be written for novices still use language that is, and assume that the user is familiar with terms that are, beyond the novice level - which is pretty much as Barker puts it, a failure to write so the user can easily perform the task.
To me, the instructions that avoid these failures, do, as Nate stated, use active voice, present steps in numbered list format (one step per number), use numbers only for steps, use simple sentence structure, and use terms appropriate for the audience --- and diagrams are good too.
What's wrong with passive voice?
Nate, can you give us a "real" example of passive voice in actual instructions? As a technical writer I could imagine myself instructing the user as I wrote the help topics. In that way I would stay focused on writing effective instructions: 1. To launch the Print dialog box in MSWord, click Print in the File menu. If I write in passive voice: 1. Print in the File menu is clicked to launch the Print dialog box in MSWord. As a user, which one do you prefer?
Monday, April 05, 2004
Welcome Amber
As technical writers we may have some difficulty understanding our audiences. (See Barker's quote below.) How do you know what level of expertise to write for? What language to use? Can we get their feedback? How do you know if you are writing the manuals to the skidsteer operators, the managers of the operators? the lawyers (in case there is a lawsuit)?
As a technical writer in a software company, I was writing to a select group of auto design engineers who would be using the software that my company marketed. We would get some calls in to tech support and that was one of the ways we could figure out what our audience wanted.
As a technical writer in a software company, I was writing to a select group of auto design engineers who would be using the software that my company marketed. We would get some calls in to tech support and that was one of the ways we could figure out what our audience wanted.
