Segment Documentation: Writing Definitions the Next Owner Can Actually Use

A segment is only as durable as its documentation. A usable definition records the business purpose, the exact inclusion and exclusion rules in plain language, the data fields and logic behind them, the owner, the refresh cadence, and the treatments the segment should and should not receive.

Segments outlive their creators, usually undocumented

Most segment libraries grow the way shared drives do: quickly, personally, and with naming conventions that made sense to one person in one quarter. When that person leaves or the platform migrates, the organisation discovers that its most used audiences are defined by logic nobody can explain. Campaigns keep running on them anyway, because stopping feels riskier than guessing, which is how years of targeting drift accumulate silently.

For more on this, see this related guide and our earlier explainer on the same theme.

The cost shows up in odd places: a legal request for how a consent segment is defined, an audit asking why a group was excluded, a new hire rebuilding a segment that already exists under a different name. Each is a small tax on missing documentation, and they compound until a migration forces the full, expensive archaeology project everyone postponed.

The minimum viable segment document

Six fields cover most of the value. Purpose: what business decision this segment exists to drive. Definition in words: who is in, who is out, stated so a non technical reader can test membership mentally. Logic: the actual fields, operators, and time windows, copied from the tool, not paraphrased. Lineage: where the data comes from and how fresh it is. Owner: a name, not a team. Review date: when this document was last confirmed against reality.

Keep the document where the segment is used, linked from the segment itself in the tool, not buried in a separate wiki nobody opens mid campaign. Documentation that requires a treasure hunt effectively does not exist at the moment of need, which is the only moment that matters.

Writing definitions that survive tools

Tools change, so record intent separately from implementation. The logic line will be rewritten at every migration, but the purpose and the plain language definition are what let a new platform reproduce the segment faithfully and let reviewers spot where the new build diverged. Include edge cases you decided: how ties break, how missing data is treated, which similar segment this one must not be confused with.

Readers also found this companion piece from our archive useful.

Version the document like code, with dated changes and the reason for each. Segment definitions drift by small edits: a window widened for one campaign, an exclusion dropped under deadline. A change log turns those quiet edits into visible decisions, and lets you answer, six months later, why this audience behaves differently from the one in last year's report.

Ownership, review, and retirement

Every segment needs a living owner accountable for its accuracy, and a review rhythm matched to how fast its underlying behaviour changes. Lifecycle segments deserve quarterly review. Stable firmographic segments can stretch to annual. Reviews should test real membership: sample ten members and check each against the documented definition by hand. Documents that are never tested against data become fiction with formatting.

Retire segments deliberately. A library with two hundred audiences, half abandoned, guarantees overlap, confusion, and accidental use of stale definitions. Archiving a segment with its document preserved costs nothing and keeps the working library small enough to actually govern. The goal is a library a new team member can learn in an afternoon, because that is the library that will still be accurate next year.

Frequently asked questions

What should a segment definition include?

Purpose, a plain language statement of who is in and out, the exact field logic and time windows, data sources and freshness, a named owner, and a last reviewed date. Treatments the segment should receive, and any it must not, are worth adding.

Where should segment documentation live?

Linked directly from the segment inside the tool where it is used, with a copy in the team's central register. Documentation that cannot be found in the moment of building a campaign will not be read or maintained.

How often should definitions be reviewed?

Quarterly for fast moving lifecycle and behavioural segments, annually for stable ones, and whenever the underlying data or platform changes. Sample actual members against the document during review to catch drift between words and logic.

Why version segment documents?

Because small, undocumented edits accumulate into major drift. A dated change log with reasons lets teams explain performance changes, reproduce segments after migrations, and answer audit questions without reconstruction projects.