Your Admin Guide Documents Every Setting and Explains None of Them

Clinton De Young Product Documentation

Open the admin guide for almost any enterprise product and you'll find a page like this:

Session timeout. Sets the session timeout.

Enable strict sync. Enables strict sync.

Retention mode. Selects the retention mode. Options: Standard, Extended, Legacy.

Every setting is documented. None of them is explained. The page restates the label on the screen, lists the allowed values, and stops exactly where the administrator's real question begins: which one should I pick, and what happens if I pick wrong?

So the administrator does what any careful person does with a production system. They open a ticket. Or they ask their account manager. Or they schedule a call with your solutions engineer, who spends forty minutes walking through options that could have been written down once. Multiply that by every new enterprise customer, and your settings reference has quietly become one of the most expensive pages you own.

A reference that restates the UI isn't documentation

Settings pages usually get written last, under deadline, by whoever has a list of the configuration keys. The fastest way to "cover" a setting is to turn its label into a sentence. That produces a page that looks complete in a review and helps no one, because the reader already saw the label. They're on your docs page because the label wasn't enough.

What the administrator needs is the information that lives in the code, in the design doc, and in your senior engineer's head:

  • What the setting actually changes. Not "enables strict sync," but what the system does differently when it's on.
  • Why the default is the default. If it's safe for most customers, say so. If it was chosen for backward compatibility and new customers should change it, say that instead.
  • When to change it. The situations, in the customer's terms, that call for a different value.
  • What it costs. Performance, storage, user friction, compatibility with other features.
  • Whether it's reversible. This is the one that turns a setting into a ticket. An administrator will happily experiment with a toggle they can turn back off. They won't touch one that might migrate data, invalidate sessions for ten thousand users, or lock them into a mode they can't leave.

The questions every setting should answer

Here's the template I use when I document a configuration reference. Not every field applies to every setting, but every setting should be checked against all of them:

  1. What it does, in one or two sentences, describing system behavior rather than restating the label.
  2. Default value, and whether that default is the recommended value for new deployments.
  3. When to change it, written as scenarios: "If your users sign in from shared terminals..." rather than abstractions.
  4. Trade-offs of each allowed value.
  5. Dependencies and conflicts: other settings it requires, overrides, or is ignored by.
  6. Who can change it and where: which role, which screen, and whether it can also be set through the API or a config file.
  7. When it takes effect: immediately, on next sign-in, after a restart, or only for new data.
  8. Reversibility: what happens to existing data and users if it's changed back.

Applied to the example above, a useful entry might look like this:

### Enable strict sync

When on, a record is saved only after every connected
system confirms the write. When off (the default), the
record saves locally and syncs in the background.

**Default:** Off. Recommended for most deployments.

**Turn it on if** downstream systems must never show
data that differs from this one, for example when
records feed a billing or compliance system.

**Trade-off:** Saves wait for the slowest connected
system. If one is unavailable, saves fail instead of
queuing.

**Takes effect:** Immediately, for new writes only.
Records already queued still sync in the background.

**Reversible:** Yes. Turning it off has no effect on
existing records.

That's an invented setting, but the shape is the point. An administrator reading that entry can make a decision without a meeting. They know what they're trading, what happens to their existing data, and how to back out.

Why these pages stay thin

If the template is that simple, why is it so rare? Because the answers aren't in the place the writer looks.

The person documenting settings usually starts from the UI or from a list of configuration keys. Neither tells them what the setting does internally. That knowledge sits in the code path behind the flag, in a pull request description from two years ago, or with the engineer who added it, who has since moved to another team. Writers without access to the code have to schedule time with engineers to ask, and engineers under release pressure answer briefly: "It just makes sync strict."

The result is a page written from the outside. And the settings that most need explaining are exactly the ones whose behavior is hardest to see from the outside: anything involving data migration, caching, permissions inheritance, or interaction with another feature.

How to find the settings costing you the most

You don't need to rewrite the whole reference to see a return. Start with the settings that generate conversations:

  1. Search your help desk for tickets that mention a setting's name or its configuration key. Sort by count.
  2. Ask your solutions engineers and customer success team which settings they walk customers through on onboarding calls. They'll have a list ready, usually with strong opinions.
  3. Look for settings with irreversible effects. Even if they don't generate tickets yet, they're the ones that will generate escalations when a customer changes them without understanding the consequences.
  4. Check your defaults against your own recommendations. If your team routinely tells new customers to change a default, the documentation should say so, and the product team should hear about it.

Take the top five from that list and rewrite them against the eight questions above. That's a few days of work. Then change the canned responses and onboarding scripts that cover those settings to link to the new entries. I described that loop in more detail in Your Support Team Has Already Written the Documentation You're Missing; the same principle applies here, because your solutions engineers' explanations are first drafts of the pages you need.

Keep it from drifting again

A settings reference goes stale faster than almost any other document, because settings are added and changed in small pull requests that nobody thinks of as documentation work. Two habits help:

  • Make the documentation part of adding the flag. If your team uses a pull request template, add a short section for any new or changed setting: what it does, the default, and whether it's reversible. The engineer knows those answers at that moment better than anyone ever will again.
  • Generate the skeleton, write the substance. If your settings are defined in code or a schema, generate the list of names, types, and defaults from that source so nothing goes missing. Then have a person write the parts a generator can't: when to change it and what it costs.

Why this takes an engineer who writes

Documenting configuration well means reading the code behind a setting, working out what it actually changes, and confirming edge cases like "what happens to queued records when this is turned on?" Then it means writing all of that in language an administrator can act on. I bring decades of hands-on software engineering to documentation work, and that background matters here: I can trace the behavior myself instead of booking an hour of your senior engineer's time for every flag.

If your administrators are opening tickets and booking calls to understand settings your docs already "cover," I'd be glad to help. Send me the settings that come up most often, and we can talk through what a useful reference would look like for your product. You can reach me through the contact page.