Technical Writing Tips.

[Trippy]

I've been pestering Fraggle Rocker over some stuff, and he has been infinitely tolerant of said pestering, but there are some finer points that I fine troublesome. I thought I'd share some of the discussion.

First off, keep in mind that I haven't done technical writing like I am doing now for at least a decade, so I confess to a degree of rustiness.

I originally said:
"...When considering this data..."
The context is referring to a single set of data, consisting of multiple points of data. Elsewhere I have used data as the plural, rather than the singular.

So in this instance which is correct?
"...When considering this data..."
"...When considering these data..."
"...When considering this dataset..."


Likewise, my second question is one of plurals.

I originally wrote:
"...a series of simplifying assumptions were made to eliminate properties..."
Again, the context is refering to a single group containing multiple items.
In order to conduct the process properly, it was neccessary to make more than one simplifying assumption regarding some of the properties of a single thing.

It's singular, because there was one type of thing, which had multiple instances, however, I was forced to make more than one assumption about the properties of those things.

So which is correct?
"...a series of simplifying assumptions were made..."
"...a series of simplifying assumptions was made..."

Was is the only alternative, but it makes my head hurt.

I'm raising these here because I thought the discussion might be useful to some of the other denizens of this place.

[DaveC426913]

I originally said:
"...When considering this data..."
The context is referring to a single set of data, consisting of multiple points of data. Elsewhere I have used data as the plural, rather than the singular.

So in this instance which is correct?
"...When considering this data..."
"...When considering these data..."
"...When considering this dataset..."

I would accept 1 or 2. They are ... correcter ... than 3, which is referring more to the set than the data in it.

So which is correct?
"...a series of simplifying assumptions were made..."
"...a series of simplifying assumptions was made..."

Was is the only alternative, but it makes my head hurt.

Agreed. Mine too. The but second is correct.

[rcscwc]

When considering this data..."


I would use while like

While considering this data... you should take the following precautions.

or after like.

after considering this data, the premise can be rejected.

or ON

On considering this data, some startling facts emerge.

or after like

After considering this data, no firm conclusion can be drawn.

Hmmm.

[Fraggle Rocker]

I've been pestering Fraggle Rocker over some stuff, and he has been infinitely tolerant of said pestering . . . .

Not infinitely. You have simply not encountered my limits.

I originally said: "...When considering this data..." -- The context is referring to a single set of data, consisting of multiple points of data. Elsewhere I have used data as the plural, rather than the singular.

And without going any further, that right there is your problem. All editors demand consistency. In America "data" is singular because we don't know the word "datum" exists. But if the one American who does know it writes "data are" in one sentence in his article, I will demand that he use it as a plural noun throughout. That's all there is to it.

So in this instance which is correct? "...When considering this data..." "...When considering these data..." "...When considering this dataset..."

They're all correct. You just have to pick one and throw away the others forever, or at least as long as I'm your editor.

Well actually there's nothing wrong with "this dataset," but it doesn't really have quite the same meaning as "this data." A dataset is a collection of data that has actually been collected and is recorded as bits and bytes on a magnetic medium somewhere, ready to be analyzed and manipulated by Excel, Access, or anyone who can write a program to read it. When you say "this data," you can be referring to some information that hasn't actually been catalogued yet.

Several of our students consistently arrive late. Should we consider this data and think about changing the hours of the class?

We don't know how many students do this, how late they arrive, whether they arrive at the same time because they ride together... we don't even know their names! This is not a dataset!

"...a series of simplifying assumptions were made to eliminate properties..."

None of your following text matters. The subject and verb of every sentence and clause must agree in number. The subject of this sentence is "a series." We know it's singular because it takes the indefiinite article, which has no plural counterpart. Therefore, the verb must be singular also.

A series is...

Perhaps you're confused by the prepositional phrase "of simplifying assumptions." That plays the role of a multi-word adjective, which modifies the noun "series." In America everybody slept through that class in the 7th grade, except those of us who would grow up to be writers and editors. Most Americans can't tell a preposition from a proposition and I don't know if it's any different in your country. So I just correct these things without making a big deal about it. But since you asked for comments, I explained why I corrected this one. I've always figured that anyone who's bright enough to be a scientist probably has the potential to understand the rules of grammar, at least in English where the rules are considerably simpler than, say, Latin.

It's singular, because there was one type of thing, which had multiple instances, however, I was forced to make more than one assumption about the properties of those things. So which is correct?

As I said, none of that matters. The subject of the sentence is a singular noun and it has to take a singular verb.

"...a series of simplifying assumptions was made," is the only alternative, but it makes my head hurt.

It will stop hurting if you learn the rule. The only logic that rules grammar is the logic of grammar itself, not the logic of the meaning of the sentences.

I'm raising these here because I thought the discussion might be useful to some of the other denizens of this place.

The word "netizens" has been coined.

[Trippy]

Not infinitely. You have simply not encountered my limits. And without going any further, that right there is your problem. All editors demand consistency. In America "data" is singular because we don't know the word "datum" exists. But if the one American who does know it writes "data are" in one sentence in his article, I will demand that he use it as a plural noun throughout. That's all there is to it.They're all correct. You just have to pick one and throw away the others forever, or at least as long as I'm your editor.

So it's "This datum..." or "These data..."
No more treating Data like sheep.

And in the context of the report I'm writing "these data..." would probably be the correct one to use because it is given context by the preceeding paragraphs, which are discussing multiple points within a single set. Correct?

Well actually there's nothing wrong with "this dataset," but it doesn't really have quite the same meaning as "this data." A dataset is a collection of data that has actually been collected and is recorded as bits and bytes on a magnetic medium somewhere, ready to be analyzed and manipulated by Excel, Access, or anyone who can write a program to read it. When you say "this data," you can be referring to some information that hasn't actually been catalogued yet.

Several of our students consistently arrive late. Should we consider this data and think about changing the hours of the class?

We don't know how many students do this, how late they arrive, whether they arrive at the same time because they ride together... we don't even know their names! This is not a dataset!

And in that sense what I have is a dataset, although it's predictive rather than indicative. I'll stick with "these data..." Yesterday afternoon it looked awkward. This morning I can't see why I objected to it.

None of your following text matters. The subject and verb of every sentence and clause must agree in number. The subject of this sentence is "a series." We know it's singular because it takes the indefiinite article, which has no plural counterpart. Therefore, the verb must be singular also.

A series is...

Perhaps you're confused by the prepositional phrase "of simplifying assumptions." That plays the role of a multi-word adjective, which modifies the noun "series." In America everybody slept through that class in the 7th grade, except those of us who would grow up to be writers and editors. Most Americans can't tell a preposition from a proposition and I don't know if it's any different in your country. So I just correct these things without making a big deal about it. But since you asked for comments, I explained why I corrected this one. I've always figured that anyone who's bright enough to be a scientist probably has the potential to understand the rules of grammar, at least in English where the rules are considerably simpler than, say, Latin.

I studied Latin, once upon a very long time ago.

I understand the rule, it just doesn't always get applied properly. Usually in the afternoon, when I tend to have more trouble focusing.

As I said, none of that matters. The subject of the sentence is a singular noun and it has to take a singular verb.


It will stop hurting if you learn the rule. The only logic that rules grammar is the logic of grammar itself, not the logic of the meaning of the sentences.

Again, funnily enough this morning I'm sitting here scratching my head wondering why it felt awkward.

"Simplifying assumptions were made..." or "A series of simplifying assumptions was made..."

[Fraggle Rocker]

So it's "This datum..." or "These data..." No more treating Data like sheep.

Indeed. If you ever use the word "datum," then you've backed yourself into a corner and you have to treat "data" as plural.

And in the context of the report I'm writing "these data..." would probably be the correct one to use because it is given context by the preceeding paragraphs, which are discussing multiple points within a single set. Correct?

You're still not getting it! The only logic in grammar is grammatical logic, not the logic of the realm of discourse. You can say "this data" as long as you are consistent and always treat "data" as a singular noun, foreswearing the word "datum."

And in that sense what I have is a dataset, although it's predictive rather than indicative. I'll stick with "these data..." Yesterday afternoon it looked awkward. This morning I can't see why I objected to it.

Probably because at least 90% of the anglophone population uses "data" as a singular noun and does not have the word "datum" in their vocabulary. It looks awkward because it sounds awkward, and it sounds awkward because you can go a long time without hearing anyone say it that way.

"Simplifying assumptions were made..." or "A series of simplifying assumptions was made..."

What I haven't pointed out is the fact that in vernacular speech people say things like "a series of tests were performed" all the time. They even write that way in their e-mail and on internet boards.

Their brain is saying: Let's see now. "A series of tests" is just a more vague version of "five tests." "Five tests" is plural, so "a series of tests" must also be plural.

They're making the mistake of applying contextual logic to grammar, instead of grammatical logic. Which is easy to do, since very few people have studied grammar formally. "A series of" sounds like an adjectival phrase.

English does not, historically, have the paradigm of the adjectival phrase. But lately we have created it, although it is not of the type "a series of." It's the noun-adjective compound. A user-friendly interface, a fuel-efficient engine, a labor-intensive process. A hundred years ago this was very rare, but today it's a living paradigm, which means we can add new members to it any time we want, so long as we have a consensus of the other anglophones.

Even without that consensus, people say things like "I live in a dog-intolerant neighborhood," or "This is an immigrant-hostile city."

[Trippy]

You're still not getting it! The only logic in grammar is grammatical logic, not the logic of the realm of discourse. You can say "this data" as long as you are consistent and always treat "data" as a singular noun, foreswearing the word "datum."

A simple miscommunication betwixt thee and me, I think.

By "In the context of this report..." I simply meant that because I have consistently used data as the plural up until that point, and because in the paragraphs that the statement refers back to I am discussing multiple data points, for the sake of consistency I should use "These data..." over "This datum..."

Given that I have consistently used Data as plural up until this point, it also makes sense to use "these data" over "this datum", on the grounds that it consits of a location and a density, both of which are the subject of the discussion.

It looks awkward because it sounds awkward, and it sounds awkward because you can go a long time without hearing anyone say it that way.

That's precisely it, you've hit the nail on the head.

I often subvocalize while I write. The theory, at least, being that it will help with sentence structure. Apparently, however, subvocalization requires less air than reading aloud.

What I haven't pointed out is the fact that in vernacular speech people say things like "a series of tests were performed" all the time. They even write that way in their e-mail and on internet boards.

Infectious negligence then.

[Fraggle Rocker]

I often subvocalize while I write. The theory, at least, being that it will help with sentence structure.

I never heard that one. Many people subvocalize and none of us really knows whether we're one of them without being tested. People used to move their lips, so we're making progress.

Apparently, however, subvocalization requires less air than reading aloud.

And it also annoys the guy in the next cubicle a whole lot less.

Infectious negligence then.

Well but hey, this is how language evolves. Forms that were once useful in the circumstances in which our ancestors lived are no longer useful and just become hindrances. My professional pedantry notwithstanding, it is a little silly to contemplate the idea that something that's so difficult to get right could possibly be so important!

I've said this several times about English prepositions because they really stand out as virtually devoid of specific meanings, but many of the rules of English seem to only serve one purpose: to make it easy to identify a foreign speaker.

[iceaura]

I've said this several times about English prepositions because they really stand out as virtually devoid of specific meanings,

A strange blind spot for a writer, I still think - also in a writer, for a different aspect (the continuation "to have" no longer makes sense),

and stretchable to "on a writer" for a bent take,

but not "of a writer", which would mean something completely different.

[Fraggle Rocker]

A strange blind spot for a writer, I still think - also in a writer, for a different aspect (the continuation "to have" no longer makes sense), and stretchable to "on a writer" for a bent take, but not "of a writer", which would mean something completely different.

If two native anglophones and two foreign students said to you, respectively, "for a writer," "in a writer," "on a writer," and "of a writer," I think you would interpret their sentences the same way.

Obviously there are plenty of cases where a preposition can make a world of difference: to/from, with/without, on/in, etc. But I'll wager that if you examine a few pages of prose on different subjects and do a tally, the vast majority of the prepositions will be noise-words.

[rcscwc]

Being a trained and professional Civil Engineer, I know how to write a technical report. But our engineering reports are clear, cogent, precise and concise. A flowery language is not required. Fraggle might find a 1001 linguistic problems, but it does not matter in the least.

My report might say: A net head of Maximum 153.6 feet is available, with an average of 95.2 feet at 90% reliability. So a Francis turbine turbine, designed for those limits, is recommended for optimum operations. Further, all techno-economic projections are based on these findings.

What is wrong there Fraggle? It might mean NOTHING to you, but ALL to an appraiser.

[iceaura]

If two native anglophones and two foreign students said to you, respectively, "for a writer," "in a writer," "on a writer," and "of a writer," I think you would interpret their sentences the same way.

Uh, no, and neither would you.

example: that is a good dinner for a writer; that is a good dinner on a writer; that is a good dinner in a writer; that is a good dinner of a writer.

or even very general and unspecific: that is bad for a writer; that is bad in a writer; that is bad of a writer; that is bad on a writer.

If I were aware that the person speaking was not a native speaker, I might make allowances and search for (not in, of, or on) the relevant meaning in (not for, of, or on) some larger context. Otherwise, I would take the meaning as expressed - and in (not of, for, or on) the case of the famous W quote about putting food on one's family, laugh at the discordance of meanings present in (not of, for, or on) what would be a decent joke from Stephen Colbert.

Obviously there are plenty of cases where a preposition can make a world of difference: to/from, with/without, on/in, etc. But I'll wager that if you examine a few pages of prose on different subjects and do a tally, the vast majority of the prepositions will be noise-words.

I think you come by that ridiculous assessment honestly - but you might want to try out that hypothesis on an online translation program sometime, between any language and English (you like Chinese, try that) and tally the hits and misses.

Meanwhile, my darkest suspicions regarding the reality behind the manuals, descriptions, instructions, and whatnot, that so frustrate the end user of (not in, for, at, under, with, without, about, as, or on) so much software and machinery and bureaucratic arrangements of modern life, are solidifying into exasperated judgments.

[rcscwc]

Being a trained and professional Civil Engineer, I know how to write a technical report. But our engineering reports are clear, cogent, precise and concise. A flowery language is not required. Fraggle might find a 1001 linguistic problems, but it does not matter in the least.

My report might say: A net head of Maximum 153.6 feet is available, with an average of 95.2 feet at 90% reliability. So a Francis turbine turbine, designed for those limits, is recommended for optimum operations. Further, all techno-economic projections are based on these findings.

What is wrong there Fraggle? It might mean NOTHING to you, but ALL to an appraiser.

Fraggle, do you know who might be the appraisers? World Bank, Asian Deve. Bank, IMF etc. They shall go through my report with a very, very fine tooth comb. Yeah, their funds, which are LOANS, must be returned with interest. But they want a techno-economic viability to be brought out.

Technical reports are a different genre specie. There, the science and technology speak, and dialect hardly matters.

Remember Fraggle. When Technolgy or MONET speaks, dialects do not matter. And your puritan grammer, whatever its worth, go for a toss.