Style of the manuals

Goals

We strive in our manuals and related documentation, to give you as much information as possible, as clearly as possible and as enjoyable to read as possible.

We do not follow formal styles of writing. We repeat ourselves if it is important. We make jokes if we think it will help make the material easier to understand or easier to read.

We want you to read everything that will help you – so we try to help you enjoy the experience.

If there is material that is entirely optional – it won't help you in any way other than for enjoyment, we say so. (But we don't have a lot of that, sorry.)

Some examples may feel like they are from the dawn of computing … that's because the author and half owner of the company has really been in this industry that long – these are actual personal recollections!

And we've learned from our mistakes and the mistakes of others.

We try not to use any more jargon than necessary, but where necessary we do. We try not to use a lot of highfalutin words (hmm, in this day and age, highfalutin is probably highfalutin¹!) As Winston Churchill is attributed as saying: Never use big words where a diminutive one will suffice.

Length

Sometimes the length could be made shorter. Many great men and women have been quoted more or less as Benjamin Franklin did in is 1750 letter on electricity "I have already made this paper too long, for which I must crave pardon, not having now time to make it shorter."

So too, some of our manuals could be made shorter if we spent a lot more time trying to shorten it. Sometimes we do so, but often times we instead spend the time giving you even more useful information rather than trying to wordsmith it to make it a bit shorter. So to paraphrase 20 or more famous authors: We beg your pardon if we spend our time making the software better and giving you even more useful information rather than spending the time making the existing information fit into fewer words.

Optional: Author's history/Bio of sorts

You can safely ignore this whole section, but if you ever have hands that hurt from typing, read the last 3 paragraphs.

The author of these manuals has written parts of nearly a dozen books (including a few full books²), dozens of manuals, some 100's of pages long and over 500 published technical articles long before 'blogs' came into being. He has ghost written (where someone pays for you to write as if they had written the material). For decades he has written several pages of material for staff, customers and other purposes daily. He uses 4 primary 'styles' of writing:

1. The completely informal, write the way you talk style. (Most of his articles on photography have been done in this style.)
2. A very strict 'University' style, very formal, but not pretentious, very rigid – if the same thing has to be repeated, do it exactly the same way so people don't try to figure out 'what is different'. His product manuals of the 1980's & 1990's were written in this format, so were most of the technical book writing.
3. A semi-formal. About half way between #2 and #3. The MCe manuals are written in this style. An attempt is made to be perfectly clear, consistent, but the style changes back and forth between 1st and 3rd person (I and The author) purposely done on this page. The goal is clarity of material, but make it enjoyable to read, with anecdotes that help explain the material better, and with just a touch of nostalgia or 'old' material if you prefer.
4. The push up your nose and act like you are smarter than anyone else (required style for Dr. Dobbs Journal back in the 1990's) He seldom uses this style.

Of the over 500 articles published, only two submitted were rejected – one was rejected when the author was about 10 years old, and he has his father to thank for never making that mistake again (every article submitted to a magazine after that was published, though one wasn't accepted by the 1st it was submitted to.)

My 'daddy' told me more or less: Look at what they already write, think about what they want to say and how they want to say it, think about what makes them money, then give them what will further their goals. He also told me: But never compromise by saying things you don't believe. I went on in grade 6 to have scientific articles in the field of Icheology (Fish) published around the world on a monthly basis for several years. I had one other article that was rejected a decade or so later (I still have no idea why, that magazine accepted everything else I ever submitted to them) and that article went on to be published in another journal a month later.

How we decide what to put in the manuals:

I apply the same principle to manuals, in manuals the thought process for every document is things like: 'what does the reader want' 'what does the reader need' 'what will give the reader the most value' 'what will make it interesting enough that reader will read everything they need to read'. Have I succeeded? You be the judge. If you find information missing or wrong, please let us know and we'll try to improve it.

I put in what I consider 'humorous' or 'interesting' additional material, in those cases I tell you you can safely ignore it – the following is an example to illustrate (and it is interesting at least to the author.)

Dvorak keyboard vs QWERTY – why would anyone be so crazy as to switch from QWERTY?

Interesting side note that you can safely ignore and skip past: In the 1980's I wrote so much every day that I started to develop Carpel Tunnel Syndrome or Repetitive Stress Injury (Though I don't think we had a clue what that was back then). Every day, on the drive home, I would massage the backs of my hands trying to get rid of the constant pain. I then found out about the Dvorak keyboard layout and switched to it (having used the QWERTY keyboard layout since I was 11 years old). It took a month before my Dvorak speed was as fast as my QWERTY was a month before … but most astonishing, within 3 days of switching, I never again had to massage my hands for the pain.

I know that most people think I'm crazy to use a non-standard layout, but I've converted a half dozen of my staff through the years (one who became my wife) and 2 of our 8 children to the Dvorak keyboard layout.

If your hands hurt from typing … consider whether it is worth the month it will take for you to retrain your hands to use this better keyboard. There is lots on the internet explaining why the Dvorak keyboard is better for your hands than QWERTY so I won't repeat it here, and some unions have, from time to time, tried to force companies to let employees retrain. My companies simply gave/give every employee the choice and opportunity.

Optional: Some other related quotes & near quotes to end this section with:

A synonym is a word you use when you can't spell the word you wanted. (Based on Burt Bacharach)

No man means all he says, and yet very few say all they mean, for words are slippery and thought is viscous. – Henry Brooks Adams

Words, as is well known, are the great foes of reality – Joseph Conrad.

When ideas fail, words come in very handy. – Johann Wolfgang von Goethe

Once a word has been allowed to escape, it cannot be recalled. – Horace.

Kind words can be short and easy to speak, but their echos are truly endless. – Mother Teresa

Never lose the chance of saying a kind word. – William Makepeace Thackeray