Ok, in case no one has time to "hunt" for that article from Nigel:

The Accidental Technical Writer

In 1978 I was working in England for an electronics company. The company made custom-built measurement systems that used line-scan cameras and Z80 microprocessors. My job was to design the computer system we used in each case and write the software. The software was all Z80 assembly language and the computer systems were about as powerful as a talking birthday card is today.

Each system we built had a manual written for it so the customer could hopefully understand how to use it. I hated writing the manuals but it was part of my job to document the design and how the software worked.
At the time, the sort of manuals I read were written by engineers at Tektronix or Hewlett-Packard. I loved these manuals. I’d spent a good deal of my childhood reading them and much of what I knew about electronics came from them. There was nothing more interesting than the technical reference for an oscilloscope!

In my own writing I tried to mimic the style of those electronic equipment manuals. They all had an antiseptic, formal style totally devoid of life but were at least informative. The problem I had was everything I wrote seemed to me to sound like it was written by a five-year old kid.
I’ve never been keen on reading my own work and I suspect that a lot of that problem stems from the days and days of struggling through the creation of technical manuals for the equipment I built. So as far as possible, I’d write the draft and then try very hard not to ever touch it again.

All in all, I pretty much hated what I wrote. It was embarrassing as prose and I’m not sure it was all that helpful either.

One Saturday I was having a beer with a retired friend who had been a technical writer for the British government. I was complaining about the hateful manual writing I had to do. After I’d gone on about the misery at some length he said: “Tell me what those machines you build do”. So I spent the next half hour explaining how we measured things like bread dough thickness or the weight of a gob of glass with cameras and computers.

After the explanation he said: “So why don’t you just write down exactly what you told me. It was quite clear to me what the machine does and how it works and that’s the purpose of a manual.”. I wasn’t sure I understood and asked “What – write it like I was speaking? Can you do that? I’ve never read a manual like that.”.

It took a while for him to convince me that I could, in fact, write the manuals as though I were standing in front of the user telling the story of how the machine was built and how it worked.

The first time I tried writing technical documents in the first person, I was terrified that whomever read it first would say it was crap and suggest I learn to write more formally. That didn’t happen - nobody complained so I adopted that style of writing.

Some time later I came across a book written in 1890 by a man called Buchan. the book is about plumbing and is written in first person. The book describes in detail Buchan’s opinions about plumbing, why he works the way he does and why other people’s techniques are not as good. The book is compelling reading. You really get the feeling he knows his stuff and it instills great confidence in his techniques. His writing technique really reinforced the idea that I could write in first person and not only get away with it but also help my reader to get engaged with the subject.

Later in my career I became a writer for a group at Microsoft. All of the writers were programmers like myself who were being ‘helped’ to write technical articles about the Windows operating system. We had an excellent editorial staff who worked with us to get the style right and in some cases to render the jumble of words in basic English.

My relationship with my editor Diane started as a bit adversarial because I had developed my own style by then and was pretty unwilling to change it. Diane spent a good deal of her editorial time writing the question: “To what does ‘it’ refer?” on my work. Eventually I came to view Diane as a resource. She helped me explain my points clearly yet to retain my own style. Between us we wrote some 70 or so technical articles during a three year period. That era ended with me writing my first book which Diane edited the first draft of. The book was published by Microsoft Press who assigned me a wonderful editor to take the project to completion. The book won an award.

So to summarize what I’ve learned about technical writing:

1. Write your own story in your own words. Talk to your audience as you would if they were standing in front of you.
2. Take all the advice you can get from anyone with editorial experience. They can help you become a much better writer without losing your essential style.

I think Johnny Cool has a good point about jargon. Many of the WCG Help pages have too much jargon for new members and inexperienced computer users. Experienced computer users will probably find existing pages very helpful but the inexperienced need material that explains some of the jargon as they read.

I am willing to do more than just blabber on about the situation. I am willing to contribute a few pieces in HTML if they would be helpful. In fact I'm working on a page or 2, maybe 10, to explain how the result validation process works and how it determines awarding credits. When finished it will cover the deadline, quorum, the 4th WU and the various statuses (statii ?) assigned to a result during the validation process. The goal is to teach BOINC users how to read and interpret the information on the Results Status page as well as the more detailed information in the pop-up for each WU. In the end the user should be able to follow any/all of his WUs through the various stages and know exactly what is happening and why.

At this point I am not so far into the project described above that I could not drop it if someone else is already working on the same topic. I could drop that project and work on something else.

Didactylos, let me know what is needed and I'll tell you if I feel I can carry the load. I stopped writing HTML back around version 3.1 because I had no need to write more but we can work something out.

OK. Will let you know here when I have something ready. I'll probably put it up temporarily on the bandwidth limited pages that my ISP includes in my account just so you and others can critique it. When it's a finished product we may consider a better, permanent home for it.

Could I release you from the desire to describe protein folding

If I was writing about the WCG I would focus on the goals and not the science leading towards those goals you will get bogged down in all kinds of science and jargon that only Dr Bonneau and his team need to take on board

The goals are finding cures and treatments for such afflictions as Cancer Maleria, HIV if you are trying to use your web page to encourage participation it's the end game you need to focus on.

Protein folding - honestly all I need to know

The Human Genome Project has found the code of our DNA. This code produces long stringy molecules called proteins that fold up in the human body but they can only fold up in certain ways. As they are a bit like long strings of magnets, a North and a South pole will pull together but you can't stick 2 north or 2 south poles together they push each other apart. By knowing what shape they are when folded correctly scientists can find out what they do and by knowing the shape of those folded molecules they can find drug molecules that will fit to them to alter that process if, as in the case of Cancer for example, that process goes awry.

FAAH - honestly all I need to know

Scientists know the shape of the HIV Virus so we are bombarding that HIV Virus with a whole host of potential molecules to see if any will stick, a bit like velcro, with one side fuzz and the other side hooks. By finding a molecule that sticks we can use this molecule to attach an agent to the HIV Virus to prevent or slow down it's destructive action.

All of this needs brute force number crunching power would you like to help? Want to know how to get involved.......


Please feel free to correct me if my science is wrong or I've got the wrong end of the stick on the two projects we are running at the mo

I'm a big subscriber to Johnny C's accidental technical writer theory

Dave

David, I certainly agree with your statement concerning the goals. And yes, my last post quoting someone's explanation about protein folding may be a tad over the line.

Yet, if a friend emailed or called me to join in this endeavor, I would want some information *why* my participation would make a difference.

Some modicom of information of what I would be accomplishing besides crunching.

And in order to be persuaded, I would want information on the project. What are the specifics really, technically. It would not have to be a long lecture at all.

How it works (this Distributive Computing "stuff") and why. If I were told about the importance of "protein folding" in a way that would make sense to me, I would be rather encouraged.

It would not (should not) be a Tolstoy "War and Peace" kind of a thing. Yes, a small explanation about what my computer would be "calculating" or "predicting".

My nephew is a "Doubting Thomas" and likes to "cut to the chase".

However, you are "bang on" with your post.

I did see Dagorath's pod-cast, and I thought it was very well done.