Stop using tables for documenting configuration properties

by David Garcia, Principal consultant

Think of documenting configuration properties. Or a group of parameters. I'm sure the first thing that comes to mind is a table. It's a common approach, but is it the best one? Let's take the following example:

postgresql.connection.hostYesStringThe hostname of the PostgreSQL server.
postgresql.connection.portInteger5432The port on which PostgreSQL is running.
postgresql.connection.sslmodeStringpreferThe SSL mode for the connection. Available values are: disable, allow, prefer, require

Tables are often the go-to solution but aren't always the best fit for presenting complex documentation properties.

The problem with tables

Tables present some issues when used for documenting configuration properties:

  • Limited space for descriptions: Tables constrain us to the cell space, often forcing us to shorten descriptions and lose valuable information. Long descriptions, which are sometimes necessary to fully explain complex properties, don't fit well into table cells. For example, tables usually fall short if you need to explain all the available values or complex conditional conditions.

  • Horizontal scrolling: Wide tables lead to horizontal scrolling, which disrupts the reading flow. This is particularly problematic on smaller screens or when viewing documentation on mobile devices.

  • Lack of flexibility: Adding new columns, such as one for available values, requires significant editing, leading to modifications of the entire table. This can discourage updates or result in overusing the description field.

  • Unnecessary fields: Tables encourage us to create columns, even when some are not applicable for a given property. This results in many empty or irrelevant cells, cluttering the documentation.

  • Hard to edit: If you have edited a table in Markdown or RST, you already know it is not the best experience. Adding line breaks or lists within tables can be a pain.

A better approach: Description lists

Instead of tables, we prefer using description lists that focus on the specific needs of each property. Here's the format we use:


The hostname of the PostgreSQL server.


Type: String

Example: localhost


The port on which PostgreSQL is running.

Type: Integer

Default: 5432


Determines whether to use SSL and the level of verification required.

Type: String

Default: prefer

Available values:

  • disable: SSL is not used for the connection.
  • allow: First attempts a non-SSL connection. If that fails, attempts an SSL connection.
  • prefer: First attempts an SSL connection. If that fails, attempts a non-SSL connection.
  • require: SSL is used for the connection.

Why this approach works

Switching from tables to description lists solves many of the common issues we discussed.

In short, this approach provides the space needed for thorough explanations, allowing you to describe complex properties fully without being constrained by cell size.

It also removes the horizontal scrolling of wide tables, making the documentation readable on any device.

Additionally, editing becomes much more enjoyable—you can update individual properties without reworking an entire table, reducing errors and maintenance hassle.

An added bonus: Most documentation systems will generate a link for each property automatically, making it easier for your users to share specific configurations.

Overcoming potential challenges

While description lists offer advantages over tables, they are not without challenges: many documentation systems do not support complex description lists by default. Implementing this format might require coding a custom extension to handle the formatting and presentation.

Real-world examples

Here are some documentation sites that use a similar approach to document their properties:


Next time, think twice about using a table to document properties. While tables work well for small sets of data with no more than two or three columns, they fall short when dealing with complex configurations.

Now, you have another tool in your chest to enhance your documentation. Use it wisely.

Let's talk about docs.

Do you want to create great products for technical audiences? Dive into the topic with our articles on technical writing, developer experience, and Docs as Code.