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:

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:

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:

• MongoDB Configuration Parameters
• Sphinx Configuration
• Stripe API Pagination

Conclusion

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.