I'd like to see better writing in technical articles
-
Today, I was reading a Code Project article about the announcement of the new eBPF Foundation. I was taught in English 101 that the first time an abbreviation such a eBPF is used in an article, the author, as a courtesy to the reader and for clarity, should spell it out. Now, somewhere along the line, I missed what eBPF stood for, so I had to go searching. It turned out that eBPF is an extension of BPF. So, my question became--"What the HELL is BPF?" And this lead to more searches to discover that the author was talking about "Berkeley Packet Filter". So I am asking people to spell out what an abbreviation stands for the first time it is used or, as my mother would say, IWCOTABYA.
Sometimes an article's author - and I'm not just talking about CP here - assumes some knowledge about the matter being discussed. It all depends on who the target audience is. If I'm reading an article from Science magazine, I'd welcome what you're suggesting, because I'm probably not already familiar with the lingo or even some of the concepts being discussed. But as a Windows developer who reads a lot of documentation and many articles, I could see that becoming very annoying, very fast. But I suppose that's where HTML comes in, unlike a printed sheet of paper...if you're not familiar with an acronym, perhaps it could have some hover text that spells it out. That way it doesn't change the flow of the article and you can skip right over it if you don't need an explanation. Somehow I was just reminded when HTML was being introduced, and a buddy of mine had a similar thought, but taken to an extreme...his idea was that HTML meant that we could have every single word in an article link to its dictionary definition. Now *that* is abusing a tool...
-
Sometimes an article's author - and I'm not just talking about CP here - assumes some knowledge about the matter being discussed. It all depends on who the target audience is. If I'm reading an article from Science magazine, I'd welcome what you're suggesting, because I'm probably not already familiar with the lingo or even some of the concepts being discussed. But as a Windows developer who reads a lot of documentation and many articles, I could see that becoming very annoying, very fast. But I suppose that's where HTML comes in, unlike a printed sheet of paper...if you're not familiar with an acronym, perhaps it could have some hover text that spells it out. That way it doesn't change the flow of the article and you can skip right over it if you don't need an explanation. Somehow I was just reminded when HTML was being introduced, and a buddy of mine had a similar thought, but taken to an extreme...his idea was that HTML meant that we could have every single word in an article link to its dictionary definition. Now *that* is abusing a tool...
-
dandy72 wrote:
perhaps it could have some hover text that spells it out.
Now that's a really good idea! :)
dandy72 wrote:
HTML
"Go forth into the source" - Neal Morse "Hope is contagious"
-
On the other hand, if you spell out what the initialism/acronym stands for every time you use it, then you might as well not use it at all. :) I used to laugh whenever I watched one of the many UK "traffic cops"-type shows, where they'd repeatedly refer to "ANPR, which stands for Automated Number Plate Recognition". If you're going to say that every time, you might as well drop the "ANPR, which stands for" part. :laugh:
"These people looked deep within my soul and assigned me a number based on the order in which I joined." - Homer
-
Today, I was reading a Code Project article about the announcement of the new eBPF Foundation. I was taught in English 101 that the first time an abbreviation such a eBPF is used in an article, the author, as a courtesy to the reader and for clarity, should spell it out. Now, somewhere along the line, I missed what eBPF stood for, so I had to go searching. It turned out that eBPF is an extension of BPF. So, my question became--"What the HELL is BPF?" And this lead to more searches to discover that the author was talking about "Berkeley Packet Filter". So I am asking people to spell out what an abbreviation stands for the first time it is used or, as my mother would say, IWCOTABYA.
As I sit here by my PC (Personal Computer), listening to music on my DAB (Digital Audio Broadcasting) radio - in your area, FM (Frequency Modulation) radio may still be dominant - I receive an SMS (Short Message Signaling) on my GSM (Global System for Mobile communication) phone saying that I ought to see the TV (TeleVision) broadcast tonight from BBC (British Broadcasting Corporation) about people's inability to handle commonly recognized TLAs (Three Letter Abbreviations). Since the days of LP (Long Play) discs, through CDs (Compact Discs) and DVDs (Digital Versatile Discs), TLAs and ETLAs (Extended Three Letter Abbreviations) have made little sense. Streaming technology managed by HTTP (HyperText Transfer Protocol) or HTTPS (Hypertext Transfer Protocol Secure) over the IP (Internet Protocol), with content managed by HTML (HyperText Markup Language) providet by your ISP (Internet Service Provider) may gradually replace physical media. Here, at CP (Code Project), I suppose that anyone from USA (United States of America) and GB (Great Britain), and even those from EU (European Union) are familiar with many of these ETLAs. Yet, as a service to those who do not immediately recognize e.g. BMW (Bayerische Motoren Werke AG) or LG (Lucky Goldstar) I suggest that we make it a habit to explain such terms when referring to such terms. Remember that it may be essential even when referring to e.g. a bottle of Dr. (Doctor) Pepper, or when updating your CV (Curriculum Vitae).
-
On the other hand, if you spell out what the initialism/acronym stands for every time you use it, then you might as well not use it at all. :) I used to laugh whenever I watched one of the many UK "traffic cops"-type shows, where they'd repeatedly refer to "ANPR, which stands for Automated Number Plate Recognition". If you're going to say that every time, you might as well drop the "ANPR, which stands for" part. :laugh:
"These people looked deep within my soul and assigned me a number based on the order in which I joined." - Homer
-
As I sit here by my PC (Personal Computer), listening to music on my DAB (Digital Audio Broadcasting) radio - in your area, FM (Frequency Modulation) radio may still be dominant - I receive an SMS (Short Message Signaling) on my GSM (Global System for Mobile communication) phone saying that I ought to see the TV (TeleVision) broadcast tonight from BBC (British Broadcasting Corporation) about people's inability to handle commonly recognized TLAs (Three Letter Abbreviations). Since the days of LP (Long Play) discs, through CDs (Compact Discs) and DVDs (Digital Versatile Discs), TLAs and ETLAs (Extended Three Letter Abbreviations) have made little sense. Streaming technology managed by HTTP (HyperText Transfer Protocol) or HTTPS (Hypertext Transfer Protocol Secure) over the IP (Internet Protocol), with content managed by HTML (HyperText Markup Language) providet by your ISP (Internet Service Provider) may gradually replace physical media. Here, at CP (Code Project), I suppose that anyone from USA (United States of America) and GB (Great Britain), and even those from EU (European Union) are familiar with many of these ETLAs. Yet, as a service to those who do not immediately recognize e.g. BMW (Bayerische Motoren Werke AG) or LG (Lucky Goldstar) I suggest that we make it a habit to explain such terms when referring to such terms. Remember that it may be essential even when referring to e.g. a bottle of Dr. (Doctor) Pepper, or when updating your CV (Curriculum Vitae).
Member 7989122 wrote:
e.g. BMW (Bayerische Motoren Werke AG)
You missed a couple. :) Your post is seriously funny, and makes your point very well.
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows. -- 6079 Smith W.
-
Today, I was reading a Code Project article about the announcement of the new eBPF Foundation. I was taught in English 101 that the first time an abbreviation such a eBPF is used in an article, the author, as a courtesy to the reader and for clarity, should spell it out. Now, somewhere along the line, I missed what eBPF stood for, so I had to go searching. It turned out that eBPF is an extension of BPF. So, my question became--"What the HELL is BPF?" And this lead to more searches to discover that the author was talking about "Berkeley Packet Filter". So I am asking people to spell out what an abbreviation stands for the first time it is used or, as my mother would say, IWCOTABYA.
Agree. Just tell us what your mother would say. Since no one else is asking. (I googled it and the only find was CP Lounge Forum.)
"Rock journalism is people who can't write interviewing people who can't talk for people who can't read." Frank Zappa 1980
-
Agree. Just tell us what your mother would say. Since no one else is asking. (I googled it and the only find was CP Lounge Forum.)
"Rock journalism is people who can't write interviewing people who can't talk for people who can't read." Frank Zappa 1980
-
Today, I was reading a Code Project article about the announcement of the new eBPF Foundation. I was taught in English 101 that the first time an abbreviation such a eBPF is used in an article, the author, as a courtesy to the reader and for clarity, should spell it out. Now, somewhere along the line, I missed what eBPF stood for, so I had to go searching. It turned out that eBPF is an extension of BPF. So, my question became--"What the HELL is BPF?" And this lead to more searches to discover that the author was talking about "Berkeley Packet Filter". So I am asking people to spell out what an abbreviation stands for the first time it is used or, as my mother would say, IWCOTABYA.
rjmoses wrote:
Today, I was reading read a Code Project article about the announcement of the new eBPF Foundation. I was taught learned, in English 101, that the first time an abbreviation, such a eBPF like "eBPF," is used in an article, the author, as a courtesy to the reader, and for clarity, should spell it out. Now, somewhere along the line, I missed I did not know what eBPF stood for, so I had to go searching: I had to look it up. It turned out I found that "eBPF" is an extension of "BPF." So, my question becameThen, I wanted to know: "What the HELL is 'BPF'?" And this lead to more searches to discover that the author was talking about I found "BPF" stands for: "Berkeley Packet Filter." So I am asking people to spell out what anI believe articles would be improved if the authors would spell out what an abbreviation stands for the first time it is used or, as my mother would say, IWCOTABYA.
«The mind is not a vessel to be filled but a fire to be kindled» Plutarch
-
As I sit here by my PC (Personal Computer), listening to music on my DAB (Digital Audio Broadcasting) radio - in your area, FM (Frequency Modulation) radio may still be dominant - I receive an SMS (Short Message Signaling) on my GSM (Global System for Mobile communication) phone saying that I ought to see the TV (TeleVision) broadcast tonight from BBC (British Broadcasting Corporation) about people's inability to handle commonly recognized TLAs (Three Letter Abbreviations). Since the days of LP (Long Play) discs, through CDs (Compact Discs) and DVDs (Digital Versatile Discs), TLAs and ETLAs (Extended Three Letter Abbreviations) have made little sense. Streaming technology managed by HTTP (HyperText Transfer Protocol) or HTTPS (Hypertext Transfer Protocol Secure) over the IP (Internet Protocol), with content managed by HTML (HyperText Markup Language) providet by your ISP (Internet Service Provider) may gradually replace physical media. Here, at CP (Code Project), I suppose that anyone from USA (United States of America) and GB (Great Britain), and even those from EU (European Union) are familiar with many of these ETLAs. Yet, as a service to those who do not immediately recognize e.g. BMW (Bayerische Motoren Werke AG) or LG (Lucky Goldstar) I suggest that we make it a habit to explain such terms when referring to such terms. Remember that it may be essential even when referring to e.g. a bottle of Dr. (Doctor) Pepper, or when updating your CV (Curriculum Vitae).
-
rjmoses wrote:
Today, I was reading read a Code Project article about the announcement of the new eBPF Foundation. I was taught learned, in English 101, that the first time an abbreviation, such a eBPF like "eBPF," is used in an article, the author, as a courtesy to the reader, and for clarity, should spell it out. Now, somewhere along the line, I missed I did not know what eBPF stood for, so I had to go searching: I had to look it up. It turned out I found that "eBPF" is an extension of "BPF." So, my question becameThen, I wanted to know: "What the HELL is 'BPF'?" And this lead to more searches to discover that the author was talking about I found "BPF" stands for: "Berkeley Packet Filter." So I am asking people to spell out what anI believe articles would be improved if the authors would spell out what an abbreviation stands for the first time it is used or, as my mother would say, IWCOTABYA.
«The mind is not a vessel to be filled but a fire to be kindled» Plutarch
-
"vagaries" So it's the language's fault that you and other authors can't express yourself in reasonably grammatic sentences, and, phrasing that communicates effectively ? I understand that ! If there weren't so many damn platforms, and cross-platform frameworks, I could be writing web SPA's that "would just work" everywhere. :) For people who learned a second language ... they did not grow up speaking ... reasonably well, tolerance, in their use of the second language, is a good thing, particularly when the goal is communicating technical information, solutions, techniques.
«The mind is not a vessel to be filled but a fire to be kindled» Plutarch
-
"vagaries" So it's the language's fault that you and other authors can't express yourself in reasonably grammatic sentences, and, phrasing that communicates effectively ? I understand that ! If there weren't so many damn platforms, and cross-platform frameworks, I could be writing web SPA's that "would just work" everywhere. :) For people who learned a second language ... they did not grow up speaking ... reasonably well, tolerance, in their use of the second language, is a good thing, particularly when the goal is communicating technical information, solutions, techniques.
«The mind is not a vessel to be filled but a fire to be kindled» Plutarch
BillWoodruff wrote:
For people who learned a second language ... they did not grow up speaking ... reasonably well, tolerance, in their use of the second language, is a good thing, particularly when the goal is communicating technical information, solutions, techniques
I agree. The OP's statement brings to mind the old British article of faith from the time of the Empire, namely that all foreigners are naturally inferior to the British (among other reasons) because they cannot speak grammatically correct King's/Queen's English. This, for example, allowed a yobbo from the slums of Liverpool to feel superior to even the most cultured Indian. Needless to say, they were wrong!
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows. -- 6079 Smith W.
-
BillWoodruff wrote:
For people who learned a second language ... they did not grow up speaking ... reasonably well, tolerance, in their use of the second language, is a good thing, particularly when the goal is communicating technical information, solutions, techniques
I agree. The OP's statement brings to mind the old British article of faith from the time of the Empire, namely that all foreigners are naturally inferior to the British (among other reasons) because they cannot speak grammatically correct King's/Queen's English. This, for example, allowed a yobbo from the slums of Liverpool to feel superior to even the most cultured Indian. Needless to say, they were wrong!
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows. -- 6079 Smith W.
Hi Daniel, I don't have enough "context" here for me to hypothesize there is anglo-chauvinism in the OP's post. I agree with the OP that the quality of writing on many CP articles is often dreadful ... from an "absolute" standard, but, for me, useful technical content is more important than style. cheers, Bill
«The mind is not a vessel to be filled but a fire to be kindled» Plutarch
