Configuration Guides: How To Document Parameters

So, you want to document the parameters for your new Configuration Management Guide.

Download: Technical Writing Templates

Where do you start?

Here’s a checklist of what you need to capture when documenting parameters in technical documentation:

Parameter Name

Specify the name of the parameter with consideration to case sensitive naming conventions. Likewise, use the correct format and styling when entering parameters to your documents.

Download the Configuration Guide Template here.

 

Location

Specify where in the configuration file that parameter is located. For example, is it part of a specific parameter set or a section of common parameter setting?

For example: This table describes the Log parameters of the Common section:

In this case, the Log parameters are part of a common set of parameters used by the service, server, or application.

Purpose

Describe the benefit to the user when this parameter is configured. Outline what it enables them to achieve and, if necessary, any downstream impacts. For example, if you turn on this option, other options are made unavailable.

However, make sure you provide enough information for the user to understand the parameter’s purpose and also how this impacts other parts of the system, for example:

Defines a locally stored backup license file. This provides protection against interruptions occurring if the connection to the license server is lost.

Prerequisites

Describe if this parameters activities are impacted by other parameter settings, for example:

Defines if a new log file is created at the time specified by the Time parameter or when the current log file reaches the size specified by the Size parameter.

A second example is if the settings are enabled if another setting is set to a specific setting in a different parameter, for example:

Defines if messages are filtered according to the Filters parameter if the Verbosity level is set to comm.

Options

Describe the parameter options is the settings are turned on or off. For example, state which options are available and then describe the settings.

• True – describe what occurs if the True setting is selected, for example, enables statistics support.
• False – describe what occurs if the False setting is selected, for example, disable statistics support.

Default value

Some parameters come with a default value, for example, 0, 1, Yes or No. Specify the default value so it’s clear to the reader if they need to change the setting or leave it in its default status.

Use the following phrasing: This is the default value.

Impact

Highlight if this setting impacts other parts of the system, for example, it overrides another parameter’s settings, disables another feature, or impacts the performance of the system.

Related documentation

If necessary, direct the reader to other sources of information which may help them understand the parameter a little better. For example, if it impacts another module or system.

Mandatory

State if the parameter is mandatory.

Note – identify any recommended settings or values which must be set for the parameter to function correctly, for example:

The value of the parameter must match the value specified for the Metrics parameter.

Minimum Settings

A second example is if the parameter must be set to a specific setting, for example:

The value of the parameter must be equal or greater than the value of the TimePeriod parameter.

Multiple values

For some parameters, you can specify a default value, for example, 1000 but also highlight other possible settings, for example:

The default value is 1000. The following values can also be defined:

• 0 — no data is sent to the server.
• 1 — data is sent to the server as soon as it is collected. This value reduces performance.

How to document parameters

Describe the parameter settings as follows:

The first sentence describes the purpose of the parameter in a single sentence.

The second sentence describes the available options and highlights the default settings, for example:

The following options are available:

• True — enables statistics support
• False — disables statistics support. This is the default value.

State if the parameter is mandatory. Use the following phrasing:

This is a mandatory parameter.

Summary

The skill in documenting parameters in technical documentation is to describe both the parameter and how it affects other settings, modules, or applications.

This means, as a technical writer, you need to understand how it connects to other parts of the system.

Without this knowledge, your documentation may be adequate but not help the reader understand its impact on other products.

Download: Technical Writing Templates