On Wed, 5 Sep 2012 08:13:58 -0700 (PDT) Rich Shepard <[email protected]> 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. _______________________________________________ PLUG mailing list [email protected] http://lists.pdxlinux.org/mailman/listinfo/plug
