April 8, 2018 at 9:13 am
Comments posted to this topic are about the item Stumbling over Words
Best wishes,
Phil Factor
April 8, 2018 at 1:01 pm
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
Change is inevitable... Change for the better is not.
April 8, 2018 at 3:19 pm
Industrial patois... Well played.
April 9, 2018 at 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.
...
-- FORTRAN manual for Xerox Computers --
April 9, 2018 at 10:08 am
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.
April 9, 2018 at 11:25 am
jay-h - Monday, April 9, 2018 7:01 AMThis 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
Change is inevitable... Change for the better is not.
April 9, 2018 at 12:21 pm
Jeff Moden - Monday, April 9, 2018 11:25 AMjay-h - Monday, April 9, 2018 7:01 AMThis 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...
April 9, 2018 at 12:46 pm
Jason A. Long - Monday, April 9, 2018 12:21 PMA 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 --
April 9, 2018 at 2:21 pm
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])
April 9, 2018 at 5:46 pm
Jason A. Long - Monday, April 9, 2018 12:21 PMJeff Moden - Monday, April 9, 2018 11:25 AMjay-h - Monday, April 9, 2018 7:01 AMThis 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=BKorP55AqvgA 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
Change is inevitable... Change for the better is not.
April 10, 2018 at 2:54 am
@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
April 10, 2018 at 4:14 am
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