AKMA has been having problems with his MT installation on Windows NT 4.0. My first reaction was to say, “Dump the trash and get a real OS, Linux”, but I realized that could be less than helpful.
Reading the discussion thread where AKMA found his solution highlights how difficult it is to write about technology. Believe it or not, it isn’t all about “First, write code. Do so without error”. There is a balancing act to the coverage, and a requirement of tone and clarity for an effective technology book.
If you make incorrect assumptions about the other person’s skill level, you frustrate them and force them into a position of having to ask and re-ask questions. Never put your audience into a position of having to ask the same question more than once.
However, if you assume too low a level, then you annoy them and they usually respond with “I know that. I wasn’t asking for___. I was just asking about____.”
Mind reading helps.
I’ve authored, co-authored, or contributed to 13 books on computer technology and have written for several online and offline magazines; it never gets easier knowing what to say and how to say it. In particular, with the “Practical RDF” book I’m just now finishing (and which I should be working on, but I’m taking a break to do laundry and a little weblogging), I had to question my interpretation of how much to cover more than once. There’s a lot of material for one book — what to put in, what to leave out. Who is my audience?
(Of course, it also helps when working with a book to have excellent editors, which I do with Prac-RDF.)
I find that the best approach to tech writing is to write to a certain level, a bit lower than the book’s assumed reading audience; and then write in a matter-of-fact voice, using a casually professional manner. Whatever I do, I avoid cute. Humor is okay (why else would I call Reification “The Big Ugly” in the book?), but never talk down to your audience, and don’t get caught up in your own cleverness — your audience will cut you at the throat.
A technical writer also never, ever makes the audience feel stupid. My job as a writer is to make you excited about the techology, interested, to answer your questions before they’re asked. My job is never to make myself seem more intelligent than I am by discussing complex topics in obscure phrases. Tech writers who write to build themselves up should be forced to eat their unsold stock.
After this book is done, I mean really done, I won’t have a professional writing assignment. For the first time since 1995, I won’t have a professional writing assignment. In the almost two years I’ve had this weblog, this is the first I’ll be able to devote all my writing and my creativity to this weblog and my web sites.
I’ll be able to finish my online C# book. I’ll be able to finish my web site makeover. I’ll be able to have some fun with my photographs, and enjoy other’s photographic endevors (which are much better than my own). More time for hiking, and driving Golden Girl around the country.
I have so many tech toys I want to create. I want to create a desktop application that incorporates WYSIWYG editing and posts to MT on my server — all using the Mozilla toolkit. There’s my PostCon system and the new Quotes. And I have dozens of other things I want to create, and new technology to explore, just for fun.
There’s so many things I want to write, and so many conversations I want to have. People to meet, too. In the flesh even. Maybe I’ll even find time for romance (which I will NOT write about).
Finally, I want to become a bigger pain in the butt then I already am with the powers that be, in weblogging and in the world. I may be broke (aren’t we all?) and I may not be writing professionally, but I still have my edge, my keyboard, my weblog, my mind, and my audience. One can do a lot of damage with all that.
