[PLUG] Linux, a path to literate engineers?

[John Jason Jordan]

On Wed, 5 Sep 2012 08:13:58 -0700 (PDT)
Rich Shepard <rshepard at appl-ecosys.com> dijo:

>> Professor Susan Conrad of the PSU Department of Applied Linguistics
>> (together with others) has been instrumental in developing classes
>> designed to teach English academic writing. So far most of the
>> effort has been targeted at foreign students, but she has also
>> worked to teach English writing skills to engineers (her husband is
>> an engineer). If anyone is interested in developing classes to teach
>> skills in writing computer documentation she would be a good contact
>> person.
>
>Academic writing is not necessarily a desired outcome. It's too often
>written by academics for other academics and frequently intended to
>show off the writer's superiority. Similar to legalese designed to
>obfuscate ideas so one is required to pay a lawyer (by the hour, too)
>to translate it so it's understandable to those not in the guild.

I guess my writing skills failed me here. I was trying to point out
that if one can teach academic writing one can teach any kind of
writing. It's just a question of defining the target.

> Application developers cannot write good documentation because they know
>exactly what's going on under the hood, how things are supposed to
>work, and how they designed the application to be used. Give the
>application to an end user and watch what they do. That elucidates how
>he sees the application and is quite frequently completely different
>from how the developer sees it.

The engineers have exactly the same problem. And the classes Professor
Conrad developed have been successful in making them much better
writers of technical documents required in their field. In fact, their
basic problem was not in communicating with other engineers, but in
expressing themselves in writing to the public and non-engineer
government officials. That sounds to me like exactly the same problem
that software developers have in writing documentation.

Or to look at it another way, some software developers are able to
write effective documentation. How do they do it when (apparently) the
majority of software developers do a lousy job of documenting their
software? Susan Conrad is into discourse analysis, and she would use
the tools of that discipline to extract the methods used by successful
writers of software documentation. While I agree that discourse analysis
would be a good approach, I would start by just asking the successful
writers how they do it.