Part of the job of a technical author is to edit, review, read and understand articles that people have written. So you get a feeling for what works and what doesn’t. The primary conclusion I have drawn from this is that simplicity is key. Simplicity makes things quicker to read. It makes them easier to remember and increases the satisfaction level of the reader.
Sounds like simplicity is good, can you go too far?
Before you can simplify you need to have a clear understanding of what you are trying to say in the first place. You can oversimplify by leaving out essential information and not getting your main point across. Leaving out some essential instruction or fact may make your article shorter but not simpler.
Assuming then that you have clearly defined your goal, what can you do to simplify your writing?
Imagine you are documenting some requirements for Nomad, you’ve got a goal and you start writing down that voice in your head as it speaks, rattling off:
“In view of the fact that Nomad requires ActiveEfficiency for a certain number of its features, prior to installing Nomad, you should ensure that there is an ActiveEfficiency installation present on the network. If this is not the case the features that rely on ActiveEfficiency will consequently not be available.”
You may or may not speak like this, but regardless the initial output is usually not great for one reason or another. So then what do you do? A good idea is to first remove the redundant expressions. A redundant expression is using several words where one or two will do. For example:
In view of the fact that can be replaced by the single word as.
So applying the process we then arrive at:
“As Nomad requires ActiveEfficiency for some features, this needs to be installed before Nomad. If this is not present some Nomad features will not be available.”
Ok, now we’re getting to the heart of this sentence, but what are we saying? Isn’t it obvious that if certain features require ActiveEfficiency then they will not be available if it isn’t there? Having reduced the redundant expressions we can see the structure of our sentence more clearly understand its deficiencies and identify the changes that are required:
Nomad requires ActiveEfficiency for some of its features.
That is short and easy to understand but does it contain all the information we need? Surely it would be useful to know which features have that requirement?
Nomad requires ActiveEfficiency for the following features:
- Single-Site Download (SSD)
- Single-site Peer Backup Assistant (SSPBA)
- Integration with WakeUp
- Nomad pre-caching
So what do I conclude from that?
The result is a useful, simple statement of the Nomad requirement for ActiveEfficiency and the features that would be impacted if it is not present. This practical example shows how a straightforward simplification process can be applied to some initial verbose output to produce something that is easy to understand and informative. Hmmm, perhaps I should apply the process to this blog… but maybe I’ll just leave that as an exercise for the reader.