Stumbling over Words

  • Comments posted to this topic are about the item Stumbling over Words

    Best wishes,
    Phil Factor

  • Great article, Phil.  It should be required reading for anyone writing a blog or article or giving a presentation.

    I'll also add that articles or blog entries shouldn't be like one huge run-on sentence.  They need "breaks" in then in the form of titles and subtitles so the reader can find their way around and know what's coming up next.

    --Jeff Moden


    RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
    First step towards the paradigm shift of writing Set Based code:
    ________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

    Change is inevitable... Change for the better is not.


    Helpful Links:
    How to post code problems
    How to Post Performance Problems
    Create a Tally Function (fnTally)

  • Industrial patois... Well played.

  • This absolutely addresses a real problem. One thing that is often missing from tech docs (even consumer software instructions) is a sense of informing the user what they should expect to see or accomplish with each step. The expected outcome of the step (as well as a general hint as to what the step is to accomplish) makes people a lot more comfortable, and they know if they've gone off the trail at some point.

    "excruciating phrases such as 'heads-up', 'ameliorating concerns', 'thelearning curve', 'pushing the envelope', 'rocket science', 'going forward','zero-sum game', 'the chicken-and-egg situation', and 'win-win situation"

    Or turning nouns into verbs (like 'partnering').

    There is a whole category of corporate/government PR speak that can go on for paragraphs without actually establishing a single fact or plan of action when an issue is controversial or awkward. You can see a determined effort to be  vague to try to placate the mobs while saying exactly nothing.

    ...

    -- FORTRAN manual for Xerox Computers --

  • I consider my audience when I'm doing documentation and/or instructions.

    If the audience is outside of the technology field then I assume they know nothing and start from the very beginning. Any acronyms are clearly defined in the overview and avoided if possible/practical.

    If the audience is within the technology field I assume they know the basics of the software but not the process. So again the overview gives just than - an overview of what's going on.

    In either case I use the active verb tense and try to avoid anything that takes away from the message. I've been told that my writing style is 'terse' and sometimes need someone to put it into fluffy words for end users but overall I've found my steps work well.

    And when I'm writing process documentation I write it for the person who takes over for the person who takes over for me. Someone who has had no direct contact with me or the development of the process and has no opportunity to come back and ask questions. It's more work up front but it's also more useful down the road imo.

  • jay-h - Monday, April 9, 2018 7:01 AM

    This absolutely addresses a real problem. One thing that is often missing from tech docs (even consumer software instructions) is a sense of informing the user what they should expect to see or accomplish with each step. The expected outcome of the step (as well as a general hint as to what the step is to accomplish) makes people a lot more comfortable, and they know if they've gone off the trail at some point.

    "excruciating phrases such as 'heads-up', 'ameliorating concerns', 'thelearning curve', 'pushing the envelope', 'rocket science', 'going forward','zero-sum game', 'the chicken-and-egg situation', and 'win-win situation"

    Or turning nouns into verbs (like 'partnering').

    There is a whole category of corporate/government PR speak that can go on for paragraphs without actually establishing a single fact or plan of action when an issue is controversial or awkward. You can see a determined effort to be  vague to try to placate the mobs while saying exactly nothing.

    I don't mind people that turn nouns into verbs in their writing because the do it in conversation.  I will admit, though, that I hate a stream of buzz-words that are meant to impress without really saying much of anything.  Depending on the audience, I also don't mind jargon such as the word "performant".  I will admit that terms such as "Industrial patois" are a little annoying, especially in an article that suggests such terms be avoided. 😉

    On the subject of overuse of buzz-words, have a look at the first 8 seconds of the YouTube at the following link for a great example.
    https://www.youtube.com/watch?v=BKorP55Aqvg

    --Jeff Moden


    RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
    First step towards the paradigm shift of writing Set Based code:
    ________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

    Change is inevitable... Change for the better is not.


    Helpful Links:
    How to post code problems
    How to Post Performance Problems
    Create a Tally Function (fnTally)

  • Jeff Moden - Monday, April 9, 2018 11:25 AM

    jay-h - Monday, April 9, 2018 7:01 AM

    This absolutely addresses a real problem. One thing that is often missing from tech docs (even consumer software instructions) is a sense of informing the user what they should expect to see or accomplish with each step. The expected outcome of the step (as well as a general hint as to what the step is to accomplish) makes people a lot more comfortable, and they know if they've gone off the trail at some point.

    "excruciating phrases such as 'heads-up', 'ameliorating concerns', 'thelearning curve', 'pushing the envelope', 'rocket science', 'going forward','zero-sum game', 'the chicken-and-egg situation', and 'win-win situation"

    Or turning nouns into verbs (like 'partnering').

    There is a whole category of corporate/government PR speak that can go on for paragraphs without actually establishing a single fact or plan of action when an issue is controversial or awkward. You can see a determined effort to be  vague to try to placate the mobs while saying exactly nothing.

    I don't mind people that turn nouns into verbs in their writing because the do it in conversation.  I will admit, though, that I hate a stream of buzz-words that are meant to impress without really saying much of anything.  Depending on the audience, I also don't mind jargon such as the word "performant".  I will admit that terms such as "Industrial patois" are a little annoying, especially in an article that suggests such terms be avoided. 😉

    On the subject of overuse of buzz-words, have a look at the first 8 seconds of the YouTube at the following link for a great example.
    https://www.youtube.com/watch?v=BKorP55Aqvg

    A few years back I threatened to alter my email signature to read:
    "Jason Long
    Director Of Synergy Creation and Paradigm Shifting"

    The only objection from upper management... I couldn't use the word "director" in my title...

  • Jason A. Long - Monday, April 9, 2018 12:21 PM

    A few years back I threatened to alter my email signature to read:
    "Jason Long
    Director Of Synergy Creation and Paradigm Shifting"

    The only objection from upper management... I couldn't use the word "director" in my title...

    This fellow has probably one of the most bad*** job titles anywhere (no, I don't know him) [https://www.csefire.com/meet-the-experts]
    Dr. Joklik is a Principal Engineer and Director of Combustion

    ...

    -- FORTRAN manual for Xerox Computers --

  • Jeff Moden - Monday, April 9, 2018 11:25 AM

    I don't mind people that turn nouns into verbs in their writing because the do it in conversation.  I will admit, though, that I hate a stream of buzz-words that are meant to impress without really saying much of anything.  Depending on the audience, I also don't mind jargon such as the word "performant".  I will admit that terms such as "Industrial patois" are a little annoying, especially in an article that suggests such terms be avoided. 😉

    Is it only me or is there a ***LOT*** of word-play in this editorial?  Putting the "skill" of placing a sticky note on a whiteboard on the same level as being able to "write clearly in a logical sequence" seems a bit of a stretch.
    If I recall correctly, Phil Factor has been known to write some articles that are tongue-in-cheek.  Is this one of them?
    Of course, it could simply be my muddled understanding of Middle English that has me rather confused.

    There are few other phrases that caused me to wonder: 
         The incomplete sentence (missing the period and possibly more), "Managers are unlikely to be,"  has me doubting the existence of managers.
         Precisely how is "system shutdown" not jargon?
         And further, what is an "IT all-rounder?"  I found no glossary with a definition.  For reasons of privacy, I cannot tell you
    what it means in any of my private languages (why limit myself to one?).

         I make it a point to only use my private languages  in private.  This has helped eliminate misunderstandings that would otherwise be unavoidable.  I definitely do not assume that managers are familiar with my private languages, although I have been known to make use of an occasional thirteen-letter acronym (TLA). 

    Forgive me if I have misconstrued the meaning of this editorial.  I am strongly in favour of and admire clear writing, even though I have very limited abilities in that regard.  I also applaud and attempt to practise clear thinking.

    Trying not to stumble over the words,
    Not-An-IT-All-Rounder.  (NAITAR - which is an SLA [six-letter-acronym])

  • Jason A. Long - Monday, April 9, 2018 12:21 PM

    Jeff Moden - Monday, April 9, 2018 11:25 AM

    jay-h - Monday, April 9, 2018 7:01 AM

    This absolutely addresses a real problem. One thing that is often missing from tech docs (even consumer software instructions) is a sense of informing the user what they should expect to see or accomplish with each step. The expected outcome of the step (as well as a general hint as to what the step is to accomplish) makes people a lot more comfortable, and they know if they've gone off the trail at some point.

    "excruciating phrases such as 'heads-up', 'ameliorating concerns', 'thelearning curve', 'pushing the envelope', 'rocket science', 'going forward','zero-sum game', 'the chicken-and-egg situation', and 'win-win situation"

    Or turning nouns into verbs (like 'partnering').

    There is a whole category of corporate/government PR speak that can go on for paragraphs without actually establishing a single fact or plan of action when an issue is controversial or awkward. You can see a determined effort to be  vague to try to placate the mobs while saying exactly nothing.

    I don't mind people that turn nouns into verbs in their writing because the do it in conversation.  I will admit, though, that I hate a stream of buzz-words that are meant to impress without really saying much of anything.  Depending on the audience, I also don't mind jargon such as the word "performant".  I will admit that terms such as "Industrial patois" are a little annoying, especially in an article that suggests such terms be avoided. 😉

    On the subject of overuse of buzz-words, have a look at the first 8 seconds of the YouTube at the following link for a great example.
    https://www.youtube.com/watch?v=BKorP55Aqvg

    A few years back I threatened to alter my email signature to read:
    "Jason Long
    Director Of Synergy Creation and Paradigm Shifting"

    The only objection from upper management... I couldn't use the word "director" in my title...

    Ah... you know the rules and should know better.  You can't use "director" in your title unless you can draw 7 red lines, all perpendicular to each other, using only Blue and Green markers and one of them has to be in the shape of a bunny. 😀

    --Jeff Moden


    RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
    First step towards the paradigm shift of writing Set Based code:
    ________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

    Change is inevitable... Change for the better is not.


    Helpful Links:
    How to post code problems
    How to Post Performance Problems
    Create a Tally Function (fnTally)

  • @nelson-2
    Yes, I'm using several rhetorical devices in my editorials. In this case, I'm doing so in order to make the point that the way that teams communicate in IT is essential for success. After all, DevOps is based on the reinvention of techniques of communication that were familiar to the ancient Greeks. The message of the editorial is that there really are techniques that will enormously help the way you can get ideas across, and improve the ways that you can explain your work. I don't claim to know the answers: I was lucky to go to a school that taught debating and rhetoric. I've found the knowledge extraordinary useful since, if only when listening to others using tricks and 'committing fouls' , using guile to mislead or sway opinion by sheer emotion. I use Richard A Lanham's  'A Handlist of Rhetorical Terms' (University of California Press) which is brief and readable. There is even more rhetorical  jargon listed than the database jargon on MSDN.

    Best wishes,
    Phil Factor

  • An excellent article. In a similar vein, I find this blog has very useful examples of bad writing and how to address them
    https://withoutbullshit.com/

    Garrie Powers
    IT Developer
    Comprehensive Clinical Trials Unit at UCL
    Institute of Clinical Trials and Methodology

Viewing 12 posts - 1 through 11 (of 11 total)

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