Software manuals

Margaret Ball margaret at
Mon Dec 13 23:49:25 EST 2004

Juliette wrote

> <snip>
> Don't you think there ought to be some kind of Retribution for people 
> who tell you their software is trivially easy to use and then make you 
> download a 160 page manual, with links to five or six other manuals 
> where they actually explain the details? Something slow, with boiling 
> oil in it? </snip>
> Ouch!
> I write those books!

Ah. To clarify:

It's not the tech writers I want to dip into boiling oil. It's the 
marketing people who lured me in with promises of a hassle-free setup 

The only tech writer I ever actually wanted to hurt was a nice young 
English major who worked for the software research center where I was 
employed. He kept rearranging my sentences into what he considered more 
euphonious combinations, and I kept patiently explaining to him that you 
CHANGE THE MEANING of a sentence when you move those little bitty words 
like "all" and "or" and "not" into different locations. Well, maybe not 
so patiently. I don't think he ever did get the idea, but eventually a 
colleague told me that he'd commented, "Dr. Ball sure is touchy about 
her writing, you'd better not try to change anything.

Good technical writing is extremely demanding and I have the greatest 
respect for people who can describe complex systems clearly and 
unambiguously. I just wish there were more of them.

Margaret Ball

Mathematicians are like Frenchmen; whatever you say to them they translate into their own language and forthwith it is something entirely different.


To unsubscribe, email dwj-request at with the body "unsubscribe".
Visit the archives at

More information about the Dwj mailing list