Tell them what they need to know and why

[James Barrow]

>>If a user knows what they're trying to avoid, they're better equipped to
>>deal with a situation that isn't explicitly addressed in the documentation
>>that might seem to warrant the action you don't want them to do.
[]
>If, on the other hand, the manual says 'If you've forgotten your
>cryptographical passphrase (which I +told+ you to keep somewhere secure,
>but I figured I was probably talking to myself), continuing the
>installation using a new one will break the system +and+ unrecoverably
>trash all of your existing data' then, well... let's just say I +hope+
>they'll call tech support!

This has me thinking about the warnings that I place within my
documentation.

For argument's sake, let's assume that Tips provide useful information,
Cautions help to avoid an unhappy path, and Warnings warn of a catastrophic
result.

That being said, would you use absolute sentences in a warning even if the
thing you're warning about *may* happen?

For example, if your Testers can replicate a catastrophic error 99 out of
100 times in a step procedure, would you write:

"Warning:  If you continue with this installation your data *will be* lost"

Or

"Warning:  If you continue with this installation your data *may be* lost"

Keep in mind that my hypothetical here isn't focused on the quality of the
application, it's more about what language you would consider using to save
the end-users from ultimate doom if they perform a particular step.

- Jim