The Technical Nuances of Technical Writing

  • JESDBA

    SSC Veteran

    Points: 293

    Comments posted to this topic are about the item The Technical Nuances of Technical Writing

    _____________________________________________________________________
    -Jamie Scharbrough
    MCTS: SQL 2008R2

  • GPO

    SSCarpal Tunnel

    Points: 4450

    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

  • alex.d.garland

    Right there with Babe

    Points: 749

    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!

  • Phil Factor

    SSCoach

    Points: 19838

    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
    Simple Talk

  • Aresby

    SSC Rookie

    Points: 30

    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

  • Tobar

    SSCarpal Tunnel

    Points: 4767

    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.

  • BenWard

    SSCertifiable

    Points: 5903

    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
    ----------------------------------------

  • Phil Factor

    SSCoach

    Points: 19838

    [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, revisited

    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.

    Review: Grammarly app

    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

    Is Grammarly that good?

    Best wishes,
    Phil Factor
    Simple Talk

  • petitpere

    SSCrazy

    Points: 2520

    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)

  • jasona.work

    SSC-Forever

    Points: 49870

    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

  • ACinAZ

    SSCommitted

    Points: 1849

    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! πŸ˜‰

  • JESDBA

    SSC Veteran

    Points: 293

    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

  • JESDBA

    SSC Veteran

    Points: 293

    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

  • BenWard

    SSCertifiable

    Points: 5903

    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
    ----------------------------------------

  • mstjean

    Hall of Fame

    Points: 3310

    If you can find it, you might consider the reference, "How To Write Good"*

    πŸ˜€

    *courtesy of National Lampoon Magazine


    Cursors are useful if you don't know SQL

Viewing 15 posts - 1 through 15 (of 28 total)

You must be logged in to reply to this topic. Login to reply