As a technical writer, I work closely with subject matter experts. Often, they provide me with a raw text which I then transform into a user-friendly user guide. And as often I need to explain to them why I have modified their text so radically! I may have, for example, removed long and detailed descriptions about the functionality of a product.
These cases are of course all about different writing styles. Subject matter experts are often academically educated and thus they have learnt to write fluent and very thorough academic text. They have possibly written an academic thesis and other scientific texts. However, user guide writing has its own conventions that should be followed, just like academic writing.
Academic writing and user guide writing have several differences, such as these:
1. Academic writing is formal, not relaxed. The style of a user guide is dependent on the company’s brand, product, and customers. A user guide can be relaxed or formal. The company may have a specific tone of voice that needs to be used and very precise instructions that need to be followed when writing a user guide.
2. In academic writing, things are thoroughly explained with references to various sources of information that are carefully listed. Thus, academic texts contain lots of footnotes and often also cross-references. Those do not belong to a user guide. The user guide contents must be arranged in a logical way that supports the reader. The user guide writer must not make the reader bounce around the guide with cross-references. Footnotes must be avoided in user guides.
3. With an academic thesis, the writer needs to prove that they are capable of doing scientific research, so the writer needs to show that they know their subject inside out. When writing a user guide, the writer must think of the readers. What are their requirements, needs, and level of knowledge? The readers do not need to know everything, and the user guide writer does not need to show the reader the vast knowledge on the subject the writer has. The user guide writer needs to forget their own needs and only think about the reader’s needs. What do the readers need to know about the product and its use, and what don’t they need to know? The contents of a user guide are often regulated by a national or EU level legislation and other guidance that set very specific requirements to the user guide contents.
4. In academic writing, using the passive voice is acceptable. In user guides, the passive voice is almost always banned: it must be clear to the reader whether they need to do something or does, for example, the software do something.
5. In academic writing, the reader is not addressed directly, whereas in user guides, the reader is addressed directly with imperatives: ”Press the power key to lock the phone’s display and keys.” Compare with these: ”The phone’s display and keys can be locked by pressing the power key” and “The power key locks the phone’s display and keys”. When writing in English, the reader is addressed with ”you”.
6. The final one is especially visible when writing in English. In academic writing, modal auxiliary verbs, such as shall and will, are usable, but not in user guides. They make the text sound legalese and often very archaic and pompous. Compare these: ”Pull the switch outward.” and ”The switch shall be pulled outward.”
If you need to write user guides alongside of your regular work and are not a trained technical writer, it may not be easy to learn away from the academic writing style. Hopefully the list above helps you study your own texts from the perspective of a user guide writer. If you want to learn more, Adina arranges training in technical writing also for non-professional writers. In these trainings, we can, for example, go through your own texts and create a specific checklist that you can use when writing user guides.