Document identifier time to live for Identities

[jamessnowplow]

No description provided.

[claude]

Docs style review

Overall this reads well: the new page follows the directory + index.md convention, sidebar_position: 40 slots correctly after cross-domain-tracking (30), frontmatter is complete, and every internal link and anchor in the diff resolves (/docs/events/identifiers/index.md#tracker-generated, #reset-identifiers-on-logout, #set-a-time-to-live, /docs/identities/concepts/merges/index.md). No new external URLs were added, so nothing to check for 404s.

A few things to address:

1. No release note for a new feature

The PR documents new Console functionality (a per-identifier Time to live field, with a 180-day default). CLAUDE.md, "Release notes":

New functionality needs a release note. If a docs change documents a new feature, a behavior change, or new platform/warehouse support, add a release note in the same PR (or a follow-up PR, linked).

Add a release-notes/<slug>/index.md here, or link the follow-up PR in the description. If this documents something that shipped a while ago, that's editorial and exempt — worth confirming rather than guessing.

2. Overloaded paragraph in "When values are removed"

docs/identities/concepts/time-to-live/index.md:18 packs six independent rules into one paragraph:

"Identities records a last-seen date for an identifier value the first time it appears in an event after its type has a TTL, and updates it on each later event. The last-seen date is the current UTC date when the event is processed, not the event's own timestamp, so reprocessing an old event sets the date to today. The date never moves to an earlier day. Identities records last-seen dates asynchronously and on a best-effort basis, so a sighting can occasionally be lost. A lost sighting leaves the last-seen date earlier than the truth, which can remove a value that is still in use."

The style guide's page-structure guidance ("Introduce lists with a sentence ending in a colon", "Precede every heading and list with at least one paragraph of prose") supports breaking this up. Suggest keeping the first sentence as the lead-in and moving the behavioral rules into a list:

Identities records a last-seen date for an identifier value the first time it appears in an event after its type has a TTL, and updates it on each later event. A few details affect when a value is removed:

* The last-seen date is the UTC date when the event is processed, not the event's own timestamp, so reprocessing an old event sets the date to the processing date
* The date never moves to an earlier day
* Identities records last-seen dates asynchronously and on a best-effort basis, so a sighting can occasionally be lost

The same density applies to docs/identities/configuration/index.md:54, where three distinct TTL-change behaviors share one paragraph.

3. Dangling subject / passive construction

docs/identities/concepts/time-to-live/index.md:18:

"A lost sighting leaves the last-seen date earlier than the truth, which can remove a value that is still in use."

Grammatically, which attaches to the last-seen date, which isn't what removes anything. CLAUDE.md: "Use active voice: 'the Collector receives events'." Fix by naming the actor:

"A lost sighting leaves the last-seen date earlier than the truth, so Identities can remove a value that is still in use."

Related vagueness on line 20: "A value that appears in an event before removal reaches it gets a new last-seen date and stays." → "A value that appears in an event before Identities removes it gets a new last-seen date and stays."

4. Single-digit number written as a numeral

docs/identities/configuration/index.md:50:

"Enter a number of days between 7 and 36500"

Style guide, Grammar and spelling: "Spell out single-digit numbers as words: 'three events' not '3 events'." Suggest: "Enter a number of days between seven and 36,500" (the thousands separator also makes the upper bound readable).

5. Passive heading

docs/identities/concepts/time-to-live/index.md:16: ## When values are removed

CLAUDE.md, Headings: "Prefer imperative voice" and "Use active voice". Suggest ## When Identities removes values. ("What removal changes" is fine as-is.)

Nits

• docs/identities/configuration/index.md:52 — "Identifiers in a configuration deployed before TTL was available show as Forever." The style guide says to stay in the present tense and avoid product-timeline framing ("currently", "in the future", "latest"). Consider "Identifiers configured without a time to live show as Forever."
• docs/identities/configuration/index.md:57 — "Check how long your users go between events". CLAUDE.md: "Refer to the reader's users as 'the user'." Consider "Check how long the user typically goes between events." (Noting "your users" does appear elsewhere in the docs.)

[jamessnowplow]

Applied items 2, 3, 5, and both nits in 05b8885.

Item 1: the release note will come in a later PR.

Item 4: keeping the numerals. The Console validation message reads "Must be between 7 and 36500 days" and the help text renders the same digits, so the docs match the text the reader sees in the UI.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	documentation	05b8885	Commit Preview URL Branch Preview URL	Sep 16 2026, 03:20 PM