Configuration Guides: How To Document Parameters

If you want your customers to keep using your products, make sure every parameter settings is correctly documented.

So, how can you write glittering configuration guides that sparkle and amaze when customers print out the PDF?

Here’s how, grasshopper.

Make sure to capture the following when documenting every parameters in your technical documents.

No excuses, ok?

1. The Correct Parameter Name

Don’t copy and paste what’s in JIRA. Treble-check you have the correct parameter name.

How?

Get a sample configuration file from Team Dev. That’s what they’re there for, right?

Then 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.

Location

Specify where in the configuration file that parameter is located.

Grasshopper, is it part of a specific parameter set or a section of common parameter setting?

On your journey you must learn this…

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

We’re almost there young hopper. Pay attention.

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.

Grasshopper. Life is a series of test. And your commitment to testing must reflect this.

Download these templates to start

Acceptance Test Plan

Contingency Plan

Software Development Templates

Acquisition Plan

Conversion Plan

Software Requirements Specification

Action Plan

Cost Benefit Analysis

Software Testing

API Documentation

Database Design

Standard Operating Procedures (SOP)

Audience Analysis

Datasheet

Statement of Work

Availability Plan

Deployment Plan

System Administration Guide

Bill of Materials

Design Document

System Boundary

Business Case

Disaster Recovery Plan

System Design Document

Business Continuity

Disposition Plan

System Specifications

Business Plan

Documentation Plan

Technical Writing Templates

Business Process

Employee Handbook

Test Plan

Business Requirements

Error Message Guide

Training Plan

Business Rules

Expression of Interest

Transition Plan

Capacity Plan

Fact Sheet

Troubleshooting Guide

Case Study

Feasibility Study

Use Case

Change Management Plan

Functional Requirements

User Guide

Communication Plan

Grant Proposal

Verification and Validation Plan

Concept of Operations

Implementation Plan

White Papers

Concept Proposal

Installation Plan

Work Instructions

Configuration Management Plan

Interface Control Document

Software Development Templates

Acceptance Test Plan

Maintenance Plan

Software Requirements Specification

Acquisition Plan

Market Research

Software Testing

Action Plan

Marketing Plan

Standard Operating Procedures (SOP)

API Documentation

Needs Statement

Statement of Work

Audience Analysis

Operations Guide

System Administration Guide

Availability Plan

Policy Manual

System Boundary

Bill of Materials

Project Plan

System Design Document

Business Case

Proposal Manager Templates

System Specifications

Business Continuity

Proposal Template

Technical Writing Templates

Business Plan

Quality Assurance Plan

Test Plan

Business Process

Release Notes

Training Plan

Business Requirements

Request for Proposal

Transition Plan

Business Rules

Risk Management Plan

Troubleshooting Guide

Capacity Plan

Scope of Work

Use Case

Case Study

Security Plan

User Guide

Change Management Plan

Service Level Agreement (SLA)

Verification and Validation Plan

Communication Plan

Setup Guide

White Papers

Concept of Operations

Social Media Policy

Work Instructions

Concept Proposal

Contingency Plan

 

Configuration Management Plan

Conversion Plan