October 17, 2012 at 10:30 pm
Comments posted to this topic are about the item The Technical Nuances of Technical Writing
_____________________________________________________________________
-Jamie Scharbrough
MCTS: SQL 2008R2
October 17, 2012 at 10:38 pm
Good article, Jamie. We should apply the principles espoused therein to forum posts as well. A word of caution though. If you're going to us spelling and grammar checking software, stay away from those used by Joe Celko.:-P
...One of the symptoms of an approaching nervous breakdown is the belief that ones work is terribly important.... Bertrand Russell
October 18, 2012 at 3:28 am
I agree, great article. Any technical specialist who can combine their knowledge with the ability to write and speak clearly is going to be a lot more effective!
October 18, 2012 at 3:59 am
Beware. Neither the author nor the Grammarly site tells you the price. The Grammarly site requires you to create an 'account' before it reveals that it is going to cost you $359.95 a year. A YEAR ($139.95 if you pay a year up-front).
By itself, it isn't going to provide you with the royal road to successful writing, because it isn't necessarily going to help you to interest your readers or get a message across effectively.
This article seems to suggest that perfect grammar equates with good writing. I can give you many examples where authors manage to bore even the keenest readers with works that are constructed with perfect grammar. I can give you even more examples where books or articles are fascinating to read despite being highly quirky in their grammar and sentence construction. Entire books that are now acknowledged as classics were written in dialect. Normally, of course, professional authors have the grammar corrected by their editor, but nonetheless, the world would be a much duller place if writing was judged purely on its grammar, spelling and sentence construction. Don't be fooled, if you've got something interesting to write, then write it as best you can, since grammar, spelling and sentence construction can all be tidied up afterwards. Never let your lack of technical writing skills discourage you from delivering an interesting message.
Best wishes,
Phil Factor
October 18, 2012 at 4:56 am
Whilst we may be irritated to read "your" when the author clearly meant "you're", that won't dilute a technical paper. But it can be a bit irritating to find the same sort of mistake a dozen times because then I get to wondering whether the technical information is similarly flawed.
The more important area to take notice of is that of your intended audience. I recently read an "Enterprise" white paper about Cloud computing. It was full of meaningless, enterprise-prevalent phrases (and unexplained acronyms) which at first led me think I wasn't grasping the point of the paper. On its second read I decided the author was, in fact, just waffling and not really saying anything meaningful.
SQL Server Central papers or articles are mainly from techies talking to techies. We forgive the occasional slip of grammer (or spleling) because the content overrides that. Thank goodness.
--------------------
Ralph S Bacon
webcloudsoftware.com
October 18, 2012 at 5:19 am
Good article Jamie. I learned some things and I consider myself a fairly good writer, but as Mr. Factor 🙂 pointed out, and I would agree, sometimes turning a good phrase, or just making a point, can be more important than one standard for grammar. 🙂 Like many things in life, there are different opinions of what good constitutes good grammar and style.
<><
Livin' down on the cube farm. Left, left, then a right.
October 18, 2012 at 6:40 am
Owe eye could tell a tail or too about my spelling.
excellent article but I very much dislike Grammarly.
it said I had 8 critical errors in 1 paragraph from a systems spec I wrote.
4 spelling errors because it didn't know the name of my company or the products
1 count of punctuation which I admit was an error. Apparently we don't need to put a comma in before the word 'however'...
3 counts of passive voice. this really annoys me. there is nothing wrong with passive voice so when MS Word or some other program tells
me it's wrong I get very annoyed. It's used in British English a lot. 9 times out of 10 I'll say "The car's getting washed this weekend" and very rarely will I say "I'm going to wash the car this weekend"
So for me computer based grammar correction is a bit of a waste of time and mainly serves to aggravate me - I'm in England, I want my documents to be in British English (aka English) and not in American English - not that there's anything particularly wrong with American English, it's just not the language used in my company/country! 😀
Maybe it's because I'm a picky grumpy git but muddling up your/you're just once is often enough to make me stop reading straight away, particularly if I'm only reading the article out of curiosity and not necessity.
Ben
^ Thats me!
----------------------------------------
01010111011010000110000101110100 01100001 0110001101101111011011010111000001101100011001010111010001100101 01110100011010010110110101100101 011101110110000101110011011101000110010101110010
----------------------------------------
October 18, 2012 at 7:13 am
[p]Yup. It is the Grammarly bit that I choked on. From the first two pages of a google search....[/p]
"$140 will get you a year's worth of Grammarly, but you can guess my recommendation. Computer analysis of natural language is very tough stuff, and Grammarly has utterly flailed in the tests here. The best way to learn to write is from other humans, and $140 will buy a lot of well-written and edited books. Caveat scriptor."
Grammarly doesn’t work. As the above results show, Grammarly did not catch several of our intentional grammar and spelling errors, it had nothing to say about any of our intentionally misused words, and it makes recommendations based on 19th-century grammar superstitions. This last point is especially interesting considering that Grammarly is rather laissez-faire with new words such as winningest. Elsewhere, Grammarly is inconsistent in applying its rules. And there is no way to tell Grammarly that we are American writers, so we could spell everything in the British manner and Grammarly would not question it. There’s also no way to indicate to Grammarly the level of formality of the text being checked.
Grammarly doesn’t do all it claims to do[/url]
Grammarly is far from a substitute for the human eye (or, better yet, several). If you decide to use it, you'll need to have the confidence to recognise when you know better.
Yesterday, I tried to test Grammarly with a piece of writing by Bertrand Russell from a Routledge compilation of his called 'Why Men Fight'. ... Grammarly reported 26 writing issues in the following text. The following piece was awarded a little over 50 points out of 100. I don't have anything else to say
Best wishes,
Phil Factor
October 18, 2012 at 7:15 am
Great article and thanks for sharing your experience!
I'd add one more point to the 4 you mentioned
Read your article!
This is from my own experience as I wrote many articles I had to read in front of various audiences.
Once your article is ready, read it loud to yourself. Try to act. Modulate your voice, modulate the rhythm. And be comfortable with your voice reading the article. The aim is to catch the attention and never loose it whatever your article is about.
(BTW I'm not english)
October 18, 2012 at 7:58 am
Good article, and I've forwarded it on to one of the Supervisors here as suggested reading for staff...
But, in the last section, in the sentence:
When I was in college, one of my professors recommend the same structure-checking process for everyone...
Shouldn't "recommend" be "recommended"?
😉
Hey, I can't help it, my Mom was an English teacher for a while!
😀
Seriously, nice article!
Jason
October 18, 2012 at 9:34 am
Excellent article, and I hope it gets a lot of "eye time" across the interwebs.
But it can be a bit irritating to find the same sort of mistake a dozen times because then I get to wondering whether the technical information is similarly flawed.
Exactly! Same thing with resume's; if there are glaring errors in something that is supposed to advertise a person's capabilities, how does that reflect on your ability to be accurate and precise in your work?
Several people have pointed out the "your" and "you're" issues, so I have to throw out the "there", "their" and "they're" differences that personally drive me crazy! 😉
October 18, 2012 at 9:56 am
jasona.work (10/18/2012)
Good article, and I've forwarded it on to one of the Supervisors here as suggested reading for staff...But, in the last section, in the sentence:
When I was in college, one of my professors recommend the same structure-checking process for everyone...
Shouldn't "recommend" be "recommended"?
😉
Hey, I can't help it, my Mom was an English teacher for a while!
😀
Seriously, nice article!
Jason
Oops! See, that's what I get for not having one final set of eyes proof-read!
_____________________________________________________________________
-Jamie Scharbrough
MCTS: SQL 2008R2
October 18, 2012 at 9:58 am
ACinKC (10/18/2012)
Excellent article, and I hope it gets a lot of "eye time" across the interwebs.But it can be a bit irritating to find the same sort of mistake a dozen times because then I get to wondering whether the technical information is similarly flawed.
Exactly! Same thing with resume's; if there are glaring errors in something that is supposed to advertise a person's capabilities, how does that reflect on your ability to be accurate and precise in your work?
Several people have pointed out the "your" and "you're" issues, so I have to throw out the "there", "their" and "they're" differences that personally drive me crazy! 😉
If we're discussing personal homophones that bug us, I HATE and DESPISE the people who misuse "lose" and "loose".
Its gotten so bad I sometimes have to double check when I put "lose" because it looks strange!
_____________________________________________________________________
-Jamie Scharbrough
MCTS: SQL 2008R2
October 18, 2012 at 10:07 am
Lets make a list.
Pacifically instead of specifically
Irregardless instead of regardless/irrespective
To instead of too
Your instead of you're
Lose instead of loose
Dose instead of does
Heigth instead of Height (people round here even pronounce it th on the end in speech)
There instead of they're/their
If we can make an exhaustive list we can force all technical authors to reference this list before they publish an article and then expel them from our community if they have the audacity to incur our wrath with bad grammar.
All in favour/favor ?
😉
Ben
^ Thats me!
----------------------------------------
01010111011010000110000101110100 01100001 0110001101101111011011010111000001101100011001010111010001100101 01110100011010010110110101100101 011101110110000101110011011101000110010101110010
----------------------------------------
October 18, 2012 at 12:06 pm
If you can find it, you might consider the reference, "How To Write Good"*
😀
*courtesy of National Lampoon Magazine
Viewing 15 posts - 1 through 15 (of 27 total)
You must be logged in to reply to this topic. Login to reply