|
Wright rite.
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment
"Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst
"I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
|
|
|
|
|
... and there's the problem.
I'm an old fart, so I'm going to subject you to a story; shut up and listen, because that's the point here.
When I was in college I worked for a small consulting company. Most of the time I was writing bits of code on larger projects, thoroughly supervised by more experienced engineers. One project was different, however. A customer needed a document that would describe their computing resources (several VAXen, peripherals, data base systems, and so on) to their potential users. I got the job.
Like most engineers I loathed writing. Why express in words what you were going to do in code, or in this case, what the machines could do? Over the course of six months I wrote a 70 page document describing each of the four VAX machines, the peripherals they had, what software they were running, and so on. Pretty dry stuff, until the people in the organization who were reviewing drafts started asking questions. "Why is it like that? Why does this machine have this feature, and it's not on that machine?" and so on. This is where I learned how to write.
The first rule of writing isn't about spelling, or grammar, or what bloody font you use. It's this: CONSIDER YOUR AUDIENCE! The document you're writing has a purpose, otherwise why write it? Your job as author is to correlate that purpose to the needs, skills, and temperment of your audience. The thing that my audience reviewing my drafts pointed out was that while the basic information was useful, they also wanted to know the rationale behind the configuration. That knowledge, not available anywhere except in the system manager's heads, was important to the users making decisions. I finally realized that the purpose of this document was to help these folks decide if and how to use this organization's resources. My audience was technically-oriented but not necessarily technically proficient to understand the implications in the dry inventories that were the document's start.
The end result of this half-year stint as a technical writer has had a more profound affect on my career than any other part of my education or early experience. I no longer hate writing. When I need to do it, I can create appropriate readable and useful documentation quickly. Most of the suggested changes I get on my documentation are based on business concerns of which I wasn't aware, and even those have faded somewhat over time as I have matured.
The contempt the engineers of my generation felt for writing as a skill has been replaced by apathy and indifference today. With email, IM, text messages, social media, and so on, all of you write... a lot. The problem is the writing is ephemeral and you take the view that the quality of it doesn't matter, only the speed with which you respond is important. You can see evidence of this here on CP. Over time the writing quality in the articles has shown a steady decline. In many of them the text is only a delimiter for links to the code and sample executable. Even in cases where there is a fair amount of text in the article, it's poorly organized and doesn't express itself clearly. I'm not faulting the CP editors here, by the way. They have a thankless task just ensuring that links work and that article submissions aren't camouflaged political screeds.
The realization expressed in this Insider article is simple: maybe there is something important after all about the way we express ourselves in written text.
Software Zen: delete this;
|
|
|
|
|
Agree 100%
M.D.V.
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
I’d say, “Here, here”, but that seems a trivial response to a well-expressed post. Thank you for this.
TTFN - Kent
|
|
|
|
|
Online users are more likely to reveal private information based on how website forms are structured to elicit data, Ben-Gurion University of the Negev (BGU) researchers have determined. Totally unrelated, but what's your mother's maiden name, the street where you grew up, and the name of your first pet?
|
|
|
|
|
Manipulated?
There is a big bunch of people willing to do it... and not only for free, but accepting to be the product.
If not, FB would have never been so successful in the first place.
M.D.V.
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
Kent Sharkey wrote: Totally unrelated, but what's your mother's maiden name, the street where you grew up, and the name of your first pet? Oddly, Frankenstein, Frankenstein and Frankenstein.
|
|
|
|
|
You're Frankenstein's monster?
TTFN - Kent
|
|
|
|
|
In new proof that 2020 has been a crappy year basically everywhere, scientists have captured video evidence of octopuses randomly punching at fish, possibly for no reason other than being spiteful. Not technical, I just empathize with the octopodes
Yes, I know that's the wrong plural, but it's the coolest looking, and octopuses are cool, right?
|
|
|
|
|
We’re excited to announce the general availability of .NET 5.0 on Red Hat Enterprise Linux 7, Red Hat Enterprise Linux 8, and Red Hat OpenShift Container Platform. For those that like peanut butter on their chocolate
Or possibly in this case maple syrup on their Brussel sprouts
|
|
|
|
|
Kent Sharkey wrote: and Red Hat OpenShift Container I had to read it twice... the first time my eyes didn't want to see the "f"
M.D.V.
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
The tech giants reportedly cut a deal in 2018 in which Facebook agreed not to compete with Google’s online advertising tools. That doesn't strike me as a good way to prove you're not a monopoly
|
|
|
|
|
How was it... the enemy of my enemy...? Or something like that... wasn't it?
M.D.V.
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
Protecting its customers from ransomware attacks and preventing their spread is very important for Microsoft. "You'll never escape justice as long as there are SuperFriends."
|
|
|
|
|
If anyone is going to hold our users hostage, it's us dammit!
|
|
|
|
|
Apple Inc is moving forward with self-driving car technology and is targeting 2024 to produce a passenger vehicle that could include its own breakthrough battery technology, people familiar with the matter told Reuters. No steering wheel - it just knows where you should be going today
Or
Because you've been driving it wrong
or
Wheels an extra $5000
|
|
|
|
|
Hmmm,
Kent, those are horrible puns. You should be charged with a salt and battery.
|
|
|
|
|
we are calling it the apple icar max and max pro and you get a free iphone and a free imac and ipod and icloud and ios....
Caveat Emptor.
"Progress doesn't come from early risers – progress is made by lazy men looking for easier ways to do things." Lazarus Long
|
|
|
|
|
Kent Sharkey wrote: it just knows where you should be going today
“Where do you want to go today?” was the title of Microsoft's 2nd global image advertising campaign. - 1994!
You're mixing company slogans.
But I suspect you did that on purpose to see who would notice.
|
|
|
|
|
Marc Clifton wrote: But I suspect you did that on purpose to see who would notice Only people old enough to be adult and interested in those kind of topics back then?
M.D.V.
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
|
While 2020 was the year that companies had to get up to speed with digital, what will 2021 hold? Our global editors take a swing at the coming 12 months. Because it's that time of the year
|
|
|
|
|
The only question that matters to me is:
When I can start snogging again without wearing a mask (not to mention the 6 feet apart thing.)
|
|
|
|
|
Marc Clifton wrote: When I can start snogging
Strangers? Not if your wife/girlfriend hears about it...
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows.
-- 6079 Smith W.
|
|
|
|
|
Daniel Pfeffer wrote: Not if your wife/girlfriend hears about it...
Well, that's the problem - at the moment I am lacking either or both.
|
|
|
|