an example of some bad writing from the NWN2 manual:
A skill check is made when you apply a skill to a task. Your skill ranks and bonuses are added to a random number between 1 and 20. This skill check results in success if it equals or exceeds the Difficulty Class, or DC, of the task.
For example, consider a rogue with a +14 bonus in Open Lock. When trying to pick a simple lock with a DC of 15, the rogue will always succeed. His skill check will be as low as 15 (1 + 14) and as high as 34 (20 + 14). If he comes across a very complicated lock, however, that is DC 35, it will be impossible for him to succeed until he somehow increases his Open Lock bonus.
Here is how I might write it
A skill check is made when you apply a skill to a task.
For example, consider a rogue with a +14 bonus in Open Lock. When trying to
pick a simple lock with a DC (Difficulty Class) of 15, the rogue will always succeed.
Your skill ranks and bonuses are added to a random number between 1 and 20. This skill check results in success if it equals or exceeds the DC of the task.
In the previous example, the rogue’s skill check can be as low as 15 (1 + 14) and as high as 34 (20 + 14). If he comes across a very complicated lock, however, that is DC 35, it will be impossible for him to succeed until he somehow increases his Open Lock bonus.
- Deliberate confuse with impressive or interesting fact to grab attention. “A rogue with +14 bonus will always be able to open a +15 DC lock”
- Quick, clear explanation of why fact is true (“rogue’s skill check can be as low as 15 (1 + 14) and as high as 34 (20 + 14).
- Apply fact to greater wider concepts and pull into general principle (“Your skill ranks and bonuses are added to a random number…”)
I think this 3 step pattern:
- confuse and impress
- explain clearly why
- apply as general principle and extend
is a general formula for effective teaching and generally effective presentation
All the while, being sure to use more paragraphs (think, newspaper column) and break each simple idea into its own paragraph. You CAN have a 1 sentence paragraph, ms ashukian.
This posting is currently being edited and expanded.
Use simpler words whenever possible. see last paragraph.
Avoid repeating yourself.
Don’t use too many “aside” comments.
If you have to make something into an “aside” comment, then perhaps it doesn’t belong this piece of writing at all.
If every paragraph of your writing seems to have an “aside” comment in it, then your writing will be seen as “all over the place,” or “difficult to follow,” even if your writing appears “coherent,” and “clear” to you when you yourself read it.
If you use too many aside comments, then your writing might even appear “boring” to some readers, simply because you take a little too long to get to your point. In this case, the reader isn’t interested in the asides, even if you find them very interesting. The reader is impatient, especially in technical writing, and wants to see you make your point as quickly as possible.
Avoid using synonyms, or sets of words that mean the same thing, in a single sentence.
This next quotation is from Keisler’s free calculus text.
A second way to visualize a function is by drawing its graph. The graph of a real function f of one variable is the set of all points P(x,y) in the plane such that y = f(x). To draw the graph, we plot the value of x on the horizontal, or x-axis and the value of f(x) on the vertical, or y-axis.
Why doesn’t he just write:
A second way to visualize a function is by drawing its graph. The graph of a function f is the set of all points in the plane that satisfy y = f(x).
To draw the graph, we plot the value of x on the x-axis and the value of f(x) on the y-axis.
* Notice how I removed the words “on the horizontal,”. Really the thing here is more words that say the same thing = slower reading.
Its kind of like writing: “The dog wagged, or moved from side-to-side, his tail.”
If I need to define “wagged” for my reader, then I should do so either in the sentence immediately preceeding the sentence that uses the word “wagged”, or in the sentence immediately following the sentence that uses the word “wagged”.
“To wag one’s tail means to move it from side-to-side. And the dog was wagging his tail.”
“The dog was wagging his tail. To wag one’s tail means to move it from side-to-side.”
Now if we did that with Keisler’s sentence:
“To draw the graph, we plot the value of x on the x-axis and the value of f(x) on the y-axis. The x-axis is the horizontal axis and the y-axis is the vertical axis.”
It looks silly because the fact that “The x-axis is the horizontal axis” should be bleeding obvious. So, that’s why “the horizontal, or” needs to be removed from the original sentence. It adds no meaning or value and bogs the reader down.
Avoid repeating yourself.
Make new paragraphs as often as possible. Technical writing should be written like common newspaper articles are written. One simple thought to a paragraph.
When in doubt, create a new paragraph.
Use parenthetical commentary only when absolutely necessary to retain correctness, not to show off how smart you are or how you have special sensitivity to some nuance that others do not. “Others” do not care, really.
Nothing throws a student off or interrupts the flow (or “languistic motion characteristic”) of writing like unnecessary parenthetical commentary.
*I just made up the term “languistic motion characteristic” to prove the point here –
Here’s a good example of when TO use it:
“For example, if you choose the vp30 profile, you can write a Cg vertex program that loop a varying (non-constant) number of times.”
Every technical writer should be forced to read Strunk and White before being allowed to wield the pen.
- Avoid using the word “which”. Use “that” instead.
The phenomenon which is responsible for this is the same phenomenom which is responsible for lightening.
The phenomenon that is responsible for this is the same phenomenom that is responsible for lightening.
I realize this list is repetitive but I’m really tired now and need to sleep.
I have a huge bone to pick with Kuipers.
“We shall distinguish between two perspectives on rotations in the plane, and shall determine the effect which each has on coordinates of points in the plane. The first is rotation of the coordinate frame with respect to fixed points (vectors) in the plane; the second is rotation of points (vectors) with respect to a fixed coordinate frame.”
His writing suffers from the typical things that make an engineer’s / mathematicians writing harder to understand.
Can’t “we” just be clear?
There are two different types of planar rotation that we shall now discuss.
- A rotation of the actual coordinate frame with respect to fixed points in the plane.
- A rotation of the points with respect to a fixed coordinate frame.
The way I have written it is at least twice as fast to read, by my estimation. My criticisms are as follows:
– We know points are vectors, no need to slow us down with the parenthesis
– Use paragraphs more wisely. There was a need for a paragraph break as I have demonstrated.
– Removed the entire sentence “We shall determine the effect that each type of rotation has on the coordinates of points in the plane.” because the reader doesn’t care what you’re going to do with them yet. He’ll find out soon enough. Unless he sleeps. Let them have some degree of suspense, Kuipers.
Reading Kuipers’ writing is like trudging through a park with leaden shoes. The things he has to show you are very nice, but its the stifling formality of his writing that holds one back from enjoying the experience.