Tips and Tricks: Definitions

by Ursula McCloy, Employment Manager

What makes a good definition when writing software or hardware documentation? Here are some basic building blocks you can arrange to suit your needs.

What it is: The actual definition of the thingy.

Context of use: Why it's important/how it fits into the software or hardware (so the user understands how it's used)

Default value: Includes concept of typical or valid range of values.

Task: Required or possible tasks for user

Alternate Task or warning: In case there are a couple of tasks, or situations in which the main task does not apply.

Exception situations: When something is different than described above.

Here is a specific example of how it plays out:

Device ID

Defines the source or destination of the SECS message on the equipment. The Host uses this value when sending SECS messages, so that the messages are processed by the appropriate equipment component. If your tool is configured to use SDR to communicate with other hardware components, more than one DeviceID/Port will be defined. Port 0 is usually used to communicate with the Host. Typically, you would not change the default value, unless the factory Host is expecting to communicate with a different Device ID.

Note: If you update any of these settings, you will need to update information on the other side of the communications link (e.g., the Host), so that it uses the same settings.

General observations:

• There is just naturally one sentence for each "type" of information.
• The developer did *not* provide all this information -- some of it required a bit of “digging”.
• The order got shifted around a little, since the exception situation (more than one SDR communication link) and the default value of another setting (Port) tells the user what Device ID to modify (you kinda have to see the configuration file where this setting is to get a feel for this).
• The "Warning" actually applied to four separate settings in this configuration file, so it's pulled out at the end as a separate note.