Welcome to your new Mass Spectrometer

I have been writing some new documentation recently at work, in an attempt to render the new instrument I've been working on usable by someone other than me. When I say "new" documentation, obviously what I mean is "cobbled together from things I've written before", because only an idiot would start from scratch if they didn't have to. Or so I thought. It's always worked before. But I was always in control of the documentation before. And last year, because I was over-worked, I lost control. I am no longer the sole author.

Imagine for a moment that you have bought yourself a lovely, new mass spectrometer. You are a young, keen, environmental scientist, looking forward to collecting data and identifying patterns in atmospheric pollution. English is probably not your first language. In fact, the roman alphabet may not even be the writing system of your native language. You're really hoping that the documentation that comes with your £150,000 instrument is going to be clear enough that you'll be able to start using your new toy almost straight away. You aren't an engineer or physicist. In fact, you don't really know how this particular technique works, but you do understand the data that comes out of it, and it's the data that you're interested in.

You've fully immersed yourself in this imaginary scenario haven't you? Good. Now you can open the user manual. What's this? There are four manuals? Why are there four manuals? What are they for? This one says it's a "Hardware Reference", and seems to be full of impenetrable jargon, so you put it to one side, as it clearly has nothing in it that will tell you how to use your new machine. "User Guide", that looks more promising. Except its introductory statement tells you that you need to read and understand the "Hardware Reference" first, and that you have to read the other two manuals. What are they? They both seem to be software manuals, how odd. One of them is the software for controlling the machine, and the other for collecting the data. Surely that's the same thing?

It's at this point that I'll let you in on a secret. For historical reasons, we have two utterly separate software suites, one that controls the machine's voltages, temperatures, pressures and flows; the other suite is all about data collection, processing and analysis. They're written in different programming languages.

But you, the naive, young, non-English environmental chemist, really don't care what language any of it was originally written in, and nor do you want to have to jump back and forth between different manuals as you try and work out how to get some data. Shaking your head at the crazy people who have written this documentation, you resign yourself to reading one of the software manuals, and since you need to try and turn the machine on, you start with the software guide for operating the machine. And you are confronted with this as the very first line in the user guide:

Now that the source and optics are almost completely computer controlled, many front panel controls have disappeared, to be replaced by controls in screen dialogs. These have been added to the existing monitoring program, which now takes on both tasks.  

I think you would be justified in being, as a bare minimum, bemused by this, and at worst perhaps panic-struck to hear that controls have been disappearing. I genuinely cannot imagine what was passing through my colleague's mind when he decided that this was a suitable introductory sentence for a user guide. It makes perfect sense to me, to remind me what's changed since the version of this machine we built a couple of years ago, but not to someone who neither knows, nor cares, about the design of an instrument they don't own and will never use.

Overcoming your concerns about the sanity of the author, and the wisdom of having bought some very expensive equipment from a company in the grip of utter lunacy, you plough on, hoping to understand what's going on. You soon find yourself reading how to use the control system...

Many of the adjustable parameters require a high dynamic range in adjustment, meaning that the range of adjustment is very large compared with the smallest adjustable increment. In systems with manual controls, these adjustments would often have been made with a 10 turn dial potentiometer. Unfortunately, there are no standard Windows controls that are suitable and convenient for the task, so it has been necessary to invent a new control.  

Because a user guide is always the place to justify the author's hatred of Microsoft. You, my poor, naive, enthusiastic chemist, don't care why the control system has been designed the way it has. You don't need to know the pain we suffered when using another manufacturer's appalling control system, designed to overcome this same problem. You only need to know that what you have is simple, robust, intuitive and clear. You only need to know that you can easily and comfortably adjust 3,500V by one volt at a time with mouse or keyboard without specialist knowledge or training, and without needing the eyes of a hawk and the dexterity of a concert pianist.

So, back to the "new" documentation I'm writing. Which is now destined to actually be new, because I cannot, in good conscience, and with any sense of professional pride, have those sentences, or many of their friends and relations, in my documentation. And I'm going to take the radical step of putting all the information about how to use the instrument into a User Guide, and all the other, detailed, technical stuff into a Service Manual. Which has taken what was a fairly sizeable job and turned it into a behemoth. And I have to try and get it done quickly enough that nobody will notice the complete restructuring that I am undertaking and tell me not to "waste" time on it. And I have to get it done well enough that everyone will agree that my way is the best way, and not defend the Four Manuals of Bewilderment. Sometimes I think taking a pride in my job will be the death of me.