Wednesday, 1 June 2011
09:05 PM
Not long ago, I saw a query from someone who said that they had a bunch of subject-matter experts (SMEs) who were now writing content. The person who posted the query was looking for a course that provided some instruction on how to write effective content. The requestor then clarified the type of training the SMEs wanted — correct use of punctuation, common grammatical errors, etc.
 Reading this gave me that sinking feeling. First, there was the implicit suggestion that that you can take an SME, sit him or her down with a copy of Word, and start producing documentation. Second, that writing skills are primarily about getting commas right and knowing all that grammar stuff.
I keep trying to come up with analogies that illuminate why I found this request disappointing:- You're a native speaker of English, why don't you teach these ESL students?
- I've never sung before, but with a lesson or two, I'm sure I can sing the national anthem at the game.
- I think I'll sit down with this medical textbook and become a doctor.
- We need to create some software that does taxes. Let's hire some IRS people and teach them programming.
This is of course exaggerated, but it gets at the point, which fundamentally is that technical writing is a discipline that you don't pick up by being a native speaker and reading through a style guide. I will admit — no, I will proclaim — that there are many writers who have no formal background in writing but who are excellent writers indeed. (Including some of these "non-writer" folks.) But being good at some specialized thing is by no means a reason to think that you will be good at describing that thing to others.
And then there is this issue with punctuation and grammar. I detect this with disheartening frequency about the discipline of editing as well — that it's all about mechanics, as if being a programmer were primarily about having very keen insight into the syntax of some programming language or other. Geoff Pullum had this to say once about becoming a writer by learning rules out of a book:Look, you don't get good at writing by deleting adjectives. Writing is difficult and demanding; you can learn to get moderately good at it through decades of practice writing millions of words and critiquing what you've written or having others critique it. The good news in all this was that the requestor did get quite a lot of advice. There was, predictably, a pitch for Strunk & White. (See previous, sigh.) But people did have better suggestions as well, including the following:- Take writing classes in a cert program. In other words, don't take a class, take a program.
- Take courses in presentation principles and rhetorical principles.
- Use guidance engineering and provide examples of high-quality documentation.
- Outline, review, revise. One responder advised the SMEs to expect to produce at least three drafts.
- Perform peer reviews, including by reviewers outside the SMEs' field. (One of the responders did point out that SMEs were often too well versed in their field to recognize what non-SMEs would not know.)
A common theme among the responders was the very one that I had been despaired of in the original query — that writing well is much more about organization and structure, clarity and flow, than it is about punctuation and grammar.
Two additional suggestions I liked were these:- Set (lower) expectations for the quality of what the SMEs will be able to produce. The responder here suggested that even with a class, the SMEs would probably not be able to produce well-structured, concisely written text. "Those skills take time and practice to develop."
- "Your best investment would be a good editor."
Encouragingly, the requestor was effusive in his thanks for all the excellent advice. It's possible, of course, that he understood some of these things to begin with but that his question was not carefully framed. In any event, even if he did once think that his SMEs could be turned into writers with a dollop of training, I believe he knows better now.
[categories]
writing
|
link
|