One of the first jargon words that a rookie technical writer comes across is the end user. End user is the actual user of the product, and is most of it times, different from the client. Another term, that is often used interchangeably with end user is “layman”.
"Document the application such that even layman can understand” is one of the first doctrines that the tech writer is taught.
Unfortunately,
this sometimes leads to technical documentation that is dumbed down to hilarious levels. An ex-colleague of mine used to explain in detail how to use mouse, what are the different parts of a standard window (the menu bar, the toolbar, etc. ), and so on. It wouldn’t have been an issue, if the document he was creating was supposed to be used by system administrators, people who one can expect to have a fairly advanced knowledge about computers!
Do not use jargon
... is another mantra. Here again, I feel one needs to use the precise terms, with proper explanation, of course. While reviewing a document for marine application, I found the technical author using the term ‘ship’, whereas the operators were used to the term ‘track’ (an icon that represents ships on the screen).
Now, do not get me wrong:
... this is not to say that one should run amok with all sorts of technical terms and write as if only sys-admins will read the manual. The point here is: respect the skill level of end user, especially when you know that they will be expert users.
How does one know the skill level of the end-user?
The target audience
...is one of the important questions that you must ask during information gathering phase of any document. Ask this question to the project manager or better, ask the customer itself. Most of the times, they will be able to give you some idea about the skill level of user.
In some cases,
the target audience is rather obvious from the type of document itself: the reader of an API document can be safely assumed to know at least some basic knowledge about the syntax and the programming language; whereas online help for a school management system needs to be very descriptive as the users are likely to be non-techies.
In the case
....where you have absolutely no clue about what would be the target audience, it is a good idea to ask some of your colleagues (preferably from a different team) to run a quick eye over the document (or a representative sample of it) and gauge if they can make sense of it.
Another way
....you can keep the document simple without making it seem childish is by using extensive cross-referencing: either by embedding hyperlinks (in online documentation), or by pointing to the relevant sections (in print documentation).
And last and most important:
Always include a section on glossary and acronyms/abbreviations in (almost) all the documents that you create.
As one of the greatest physicists, Albert Einstein put it quite succinctly,
“One should always try to make things as simple as possible, but not any simpler.”
