Onlinedocs

I'm not sure how we would communicate with programmers via our documentation. It seems any effort would be in vain; we'd be producing documentation without purpose.
So, my answer is that we are in a dialgoue w/ the user to reduce the learning curve of the software interface.

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?

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.

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?

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.

I have the pleasure of announcing that our discussion this week will be taking place in collaboration with workplace professionals. I will ask them to introduce themselves in their first posting, tell us what they do, and what software tools they use at work and then to respond, when they have time, to our discussion topic for this week.

Discussion topic
On page 383 in Writing Software Documentation, Thomas Barker writes "...many problems in the language of software documentation all revolve around two central difficulties: failure to write so that the user can perform the task easily, and failure to write as if we were speaking to real human beings."

Let's discuss this claim by Barker in terms of our own experiences. Is he correct, partially correct, not at all correct? What do our professional guests have to say about this claim?

Blogger's help consists of more than just one FAQ. The help from the upper right hand corner provides access to multiple levels of user support and provides multiple means of access, such as searching and browsing.

I have not used the help system for Blogger, as the tasks I have needed to perform on Blogger have been fairly elementary, and anything I was not certain about (such as removing my accidental repeat posting), others around me knew how to do and automatically gave me the "lowdown" on it.

The help appears to be mainy procedural, taking the user through a process, but it's all in the format of a huge FAQ, all the topics being presented as questions. *gasp* I don't think I've seen something quite of that nature before...

I think Barker would be OK with this help, but I'd think he'd suggest the second level topics be titled in a parallel manner, and the third level topics be written in a gerund form.

The end.

This week let's have a look at Blogger's help docs. Is there just one FAQ? Is that the same as the help that I can access from the upper right hand corner at the question mark? Have you used the help and found it helpful? Then go back to Barker and decide where the Blogger help fits in Barker's taxonomy of help documents. Finish your entry with some comments on what you think Barker would say about Blogger's help.