The natural assumption of most software companies is that an application intended for experts in the field doesn’t need to explain anything beyond the interface. The user is supposed to know the work-flow and terms at least as well as the manual’s writer.

But the reality is that many people are trained in the field and the software at the same time. This is true not only for the application’s users, but also for its future programmers and testers. There are also users who are experts in the field but not be familiar with all its possibilities – especially ones that are unique to your application. And some might have all the required knowledge, but in a different language.

So how much background information do you provide? You need to strike the balance between leaving the user in the dark and writing an introductory course in the field. A good rule is to provide just enough information to allow the reader to search for more. Here are a few points to consider:

1. Give a general description of the standard work-flow. There is no need to list all options, but do give people a sense of where things start and end, and why.

2. Explain how each section of the interface fits into the work-flow.

3. Provide normal definitions, if such exist, and what deviating from them means.

4. List input values – range, type, format etc – and their influence.

5. It is always good to explain when certain combinations cannot exist, though it may be impractical to list all such combinations.

6. Warn users of drastic and irreversible actions.

7. Explain compatibility issues with other platforms or older versions of your application.

8. Consider adding an appendix with common terminology. This is ‘let me Google that for you’ territory, but readers will appreciate it and being an appendix – it is unobtrusive.

A user with field knowledge who is simply unaware of all options, or a user with knowledge rooted in a different language, will probably be satisfied with this information. A user with little or no knowledge will be able to find other sources to fill the gaps, using the information that you provided as the basis of a search. At the same time, you did not over-burden knowledgeable readers with background they do not need.