The Technical Nuances of Technical Writing

  • BenWard (10/18/2012)


    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 ?

    πŸ˜‰

    I'm in favor!

    Don't forget:

    bait/bate

    bear/bare

    (a million others)

    But yes, all in favor! πŸ˜€

    _____________________________________________________________________
    -Jamie Scharbrough
    MCTS: SQL 2008R2

  • Thank you for the article. I wrote something similar recently under "Writing About SQL Server"[/url].

    As Phil Factor said though, while grammar and spelling definitely matter they aren't key. They definitely should not be ignored, but content matters far more, especially in a technical piece.

    ---
    Timothy A Wiseman
    SQL Blog: http://timothyawiseman.wordpress.com/

  • Well you might be in 'favor' but I'm in favour (UK-based, you see).

    How do we get round that?

    Do you know how irritating it is to see 'color', 'neighbor', 'thru', 'OMG' (just kidding) when you're a native British English speaker?

    But as I type 'color' a zillion times a day into CSS sheets I'm blasΓ© about that one.

    Seriously, though, it raises the question of how different parts of the world treat English. Microsoft, bless them, had thousands of UK technical installers gritting their teeth at seeing the phrase 'Windows XP has gotten easier...'. That would most definitely NOT pass standard English. It would be considered just appalling here, but perfectly acceptable (I'm assuming) in the States.

    And to think we're the ones who invented the language...

    --------------------
    Ralph S Bacon
    webcloudsoftware.com

  • Aresby (10/18/2012)... 'Windows XP has gotten easier...'. ...

    As I wrote earlier, I'm not english nor am I american ... I'm luxembourgish/french.

    What would be the correct formulation for the above phrase?

  • rot-717018 (10/19/2012)


    Aresby (10/18/2012)... 'Windows XP has gotten easier...'. ...

    As I wrote earlier, I'm not english nor am I american ... I'm luxembourgish/french.

    What would be the correct formulation for the above phrase?

    The closest is "Windows has got easier". To me, that doesn't sound quite right, since "has got" usually implies possession of something. In any case, careful speakers and writers generally avoid the verb "to get", so you'd probably rephrase it something like "Windows is now easier", "Windows has become easier" or "Windows has been made easier".

    John

  • If we're discussing personal homophones that bug us, I HATE and DESPISE the people who misuse "lose" and "loose".

    I don't think you do. What you mean is that you hate and despise the confusion of the words 'lose' and 'loose'. Actually, I don't even think that you mean that. it actually merely irritates you a bit. If I was your English teacher, your work would be red-pencilled.

    And the word 'gotten' is perfectly good english, though it is considered rather archaic in British english. (It appears often in english dialect.)

    One last plea to the language-usage bigots. For quite a large proportion of those of us who read SQL Server Central, english is a second or third language. Few of us in the world choose to speak in english: it is just that the technical language of IT is currently based in english. In fact, some languages lack the words to match the english words that we've invented to describe IT things. Those of us who pride ourselves in our skill in speaking or writing in english need to be tactful, tolerant and understanding of our colleagues who are forced by circumstances to communicate in english to participate in IT internationally. Emotive sentiments like 'I HATE and DESPISE the people who misuse ...' are going to be read by people struggling with a rather irrational, intractable and irregular language: not because they want to but because they have to. How do you imagine that these guys are going to feel, reading that stuff?

    Best wishes,
    Phil Factor

  • Phil Factor (10/19/2012)


    Those of us who pride ourselves in our skill in speaking or writing in english need to be tactful, tolerant and understanding of our colleagues who are forced by circumstances to communicate in english to participate in IT internationally. Emotive sentiments like 'I HATE and DESPISE the people who misuse ...' are going to be read by people struggling with a rather irrational, intractable and irregular language: not because they want to but because they have to. How do you imagine that these guys are going to feel, reading that stuff?

    Well said. Spelling and Grammar do matter, and I would encourage anyone writing to make a reasonable effort at them. But getting the point accross clearly is what really matters. This becomes especially clear when dealing with an international audience or foreign authors writing in English.

    I try to be particularly understanding of this. I am American, but being in a military family I spent a bit of my childhood in Britain and have possibly bad tendency of mixing phrases and spellings from American and British English. I am also keenly aware that there are local differences even within America. Internationally, I speak very bad Spanish and have to ask Spanish speakers to speak very slowly and indulge me, and I must rely on translators (or the other persons knowledge of English) for any foreign language besides Spanish.

    I encourage everyone to try to use good spelling and grammar, but also to recognize that it is not at the heart of the matter, and to be particularly understanding of non-native writers.

    ---
    Timothy A Wiseman
    SQL Blog: http://timothyawiseman.wordpress.com/

  • Phil Factor (10/19/2012)


    If we're discussing personal homophones that bug us, I HATE and DESPISE the people who misuse "lose" and "loose".

    I don't think you do. What you mean is that you hate and despise the confusion of the words 'lose' and 'loose'. Actually, I don't even think that you mean that. it actually merely irritates you a bit. If I was your English teacher, your work would be red-pencilled.

    And the word 'gotten' is perfectly good english, though it is considered rather archaic in British english. (It appears often in english dialect.)

    One last plea to the language-usage bigots. For quite a large proportion of those of us who read SQL Server Central, english is a second or third language. Few of us in the world choose to speak in english: it is just that the technical language of IT is currently based in english. In fact, some languages lack the words to match the english words that we've invented to describe IT things. Those of us who pride ourselves in our skill in speaking or writing in english need to be tactful, tolerant and understanding of our colleagues who are forced by circumstances to communicate in english to participate in IT internationally. Emotive sentiments like 'I HATE and DESPISE the people who misuse ...' are going to be read by people struggling with a rather irrational, intractable and irregular language: not because they want to but because they have to. How do you imagine that these guys are going to feel, reading that stuff?

    While I completely understand your point of view, and agree with it to some degree (you're correct in that my usage of "hate" and "despise" was overly emotional), my article was intended to pinpoint the unfailing and continuous errors of the native English speaking sects in general, and American writers in particular.

    I write what I know, and what I know is that I continuously see American writers whose first language is English committing these mistakes every single day, without a care in the world for whether or not they are correct. We're all prone to mistakes, but its those who refuse to step out of ignorance that my article was really directed to.

    To put it simply: I am tired of seeing fellow Americans misuse and butcher the English language. I see it in professional environments where it should not be tolerated for even the slightest instance, and as someone who's beginning to further her path in IT, I find it, quite frankly, embarrassing. Any good presenter, any technical writer will tell you that spelling and grammar are important, and if English is your native tongue, then there's very little excuse for not checking either.

    It takes maybe an hour to have someone else look at that article you're getting ready to submit or present. Why is this so difficult? The answer is simple: it's not difficult, its inherent laziness, and I for one, wrote the article out of sheer frustration of that laziness.

    There's your answer, and there's why I feel grammar and spelling are important.

    _____________________________________________________________________
    -Jamie Scharbrough
    MCTS: SQL 2008R2

  • I often find articles written by people who speak English as a second language are done to a better standard of English that those who speak the language natively.

    I speak some French as well as English and when I write in it, I take far more care with it than I would English. As a result my written French is often better than my written English. This is probably because I know what I can get away with in English without causing my audience to struggle to understand. In French, I don't know how lazy I can be or how far I can deviate from 'proper' French and still be understood so I stick with the best French I can write.

    Lazy writing is a pet peeve of mine anyway even down to things like system generated warning messages or automatic emails with poorly written subject lines like "pgm not run.renewal Reprt FAIL!!!!" (OK that's not actually a real one and it is a bit of an exaggeration but it's indicative of the kind of thing we have had from some of our suppliers) If you're writing a program that is going to send a success or failure message every single day for the next x years spend the extra 5 minutes to write nice looking error messages!

    Ben

    ^ Thats me!

    ----------------------------------------
    01010111011010000110000101110100 01100001 0110001101101111011011010111000001101100011001010111010001100101 01110100011010010110110101100101 011101110110000101110011011101000110010101110010
    ----------------------------------------

  • BenWard (10/23/2012)


    If you're writing a program that is going to send a success or failure message every single day for the next x years spend the extra 5 minutes to write nice looking error messages!

    Gosh yes! Although this is a bit off the point of "technical writing" per se, error messages in programs generally are cobbled together and are for the benefit of the person writing the program, as s/he debugs it.

    In my experience, when a user is faced with any kind of technical message they immediately switch off and look for the nearest escape route - normally the OK button.

    Not all companies are like this; they have numbered error messages in a database and the programmer merely calls the relevant procedure to produce an English-type message (depending on who is most likely to see it). But this comes at a price and is often viewed as a nice-to-have by those controlling the finances.

    I try and encourage the use of a friendly-looking, English message that is meaningful to the end-user, with a "technical summary" underneath and a prompt to send that to the support area (who need a more specific message to be able to debug the issue).

    --------------------
    Ralph S Bacon
    webcloudsoftware.com

  • John Mitchell-245523 (10/19/2012)


    rot-717018 (10/19/2012)


    Aresby (10/18/2012)... 'Windows XP has gotten easier...'. ...

    As I wrote earlier, I'm not english nor am I american ... I'm luxembourgish/french.

    What would be the correct formulation for the above phrase?

    The closest is "Windows has got easier". To me, that doesn't sound quite right, since "has got" usually implies possession of something. In any case, careful speakers and writers generally avoid the verb "to get", so you'd probably rephrase it something like "Windows is now easier", "Windows has become easier" or "Windows has been made easier".

    John

    Thanks John for your clear explanation ...

  • BenWard (10/23/2012)


    I often find articles written by people who speak English as a second language are done to a better standard of English that those who speak the language natively.

    .../...

    The explanation here is easy ... If you write a note that needs to be understood by other persons in a language you do not master, you will read it once it's written and read it again just to make sure it's understandable, and read it again, you never know, just in case ... If people would act the same way with the notes they write, a huge number of spelling and grammar errors would be corrected before the note is published.But many don't do it, arguing a priority problem. Personally I vote for the laziness too.

    πŸ˜‰

    On the other side, the problem of english is that it is spread all over the world, spoken by millions of people. And there are far more people speaking english than there are native english speakers. There is no other language in the world that is spoken by so many foreigners. And this is also a big issue for the english language.

    I hope this makes sense.

    πŸ™‚

  • Working with SQL Server for 10+ years I confess that as a BA in English this is the least of my worries.

    Try to make a living (outside of academia) with an English degree...that's why I am where I am!

    My spell/grammar-checker is OFF.

    Cheers,

    Steve

Viewing 13 posts - 16 through 27 (of 27 total)

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