Marketing Docs Maintenance

Marketing Docs Maintenance (Diolog)

Canonical source: docs/marketing/MAINTENANCE.md in the target repo is the authoritative guide. Read it first every run — it may have evolved since this skill was written. This skill operationalises it; if the two disagree, MAINTENANCE.md wins and you should mention the drift.

The documentation set

Five maintained surfaces under docs/marketing/:

The final/ and plain/ per-area files are the working source; existing-features.md (section 2.XX) and product-feature-guide.md (section XX) are the assembled documents. Both members of each pair must agree.

Area map (01–19) — final/ and plain/ share this numbering

Inputs & intake

Establish what changed and which area(s) it touches. If unclear, ask.

• A Linear ticket (the common case) — e.g. DIO-4761. Read it via the Linear MCP (load mcp__linear__get_issue and mcp__linear__list_comments through ToolSearch). Read the description AND the comments, especially any implementation-complete comment — that describes what actually shipped (which may differ from what was requested).
• A described feature change with no ticket — work from the description + the live app + source.
• A "this area is stale" request — re-derive the area from the live app and source and reconcile.

Map the change to one or more areas (01–19). A change can span several areas (and area 19 captures cross-cutting behaviour).

Source-of-truth hierarchy

When sources conflict, trust in this order:

1. Live app (what the browser actually shows) — ultimate authority.
2. Source code (what the components render) — next authority.
3. Implementation-complete comments on the Linear ticket — what was built.
4. Ticket description — what was requested (may differ from what shipped).
5. These docs — a record, not a spec; they follow the code.

The e2e test-plan files (apps/web/e2e/test-plan/*.md) are a separate, older source documenting an earlier build. Do not use them as the authority for what exists now; when they conflict with the marketing docs, the marketing docs are more current.

Verify against the live app where you can (dev login → target page) or by reading the rendering source; don't document from the ticket alone.

Update process

For each affected area, update four files (two pairs) — and a fifth when contact/outbound surfaces change:

1. features-build/final/XX-*.md (technical detail)
2. existing-features.md → section 2.XX (technical detail; must agree with #1)
3. features-build/plain/XX-*.md (plain language)
4. product-feature-guide.md → section XX (plain language; must agree with #3)
5. outbound-contact-surfaces.md — only if a new outbound / sharing / contact surface was added (record contact-input methods, delivery channels, options)

Steps:

1. Read the ticket (description + comments).
2. Identify affected area file(s).
3. Read the current content in those files.
4. Replace outdated content — do not append UPDATE: blocks, changelog entries, or "as of DIO-xxxx" notes. The docs describe the present state only.
5. Verify four-file consistency (technical pair agrees; plain pair agrees; counts and names match across pairs).
6. Update outbound-contact-surfaces.md if relevant.

When multiple areas are affected, you may fan out one sub-agent per area (via Agent) — but give each agent disjoint area files so they don't collide, and run the shared assembled documents (existing-features.md, product-feature-guide.md) edits carefully (each area edits a different section 2.XX / XX; if agents race on the same assembled file, serialise those section edits in a final pass). Use TaskCreate/TaskUpdate to track areas.

Content standards

Technical register — existing-features.md + final/*.md

Include: component names (e.g. CompanyProfileForm, DocumentPicker); route paths (e.g. /workflows/[id], ?settings=profile); GraphQL operation names (queries/mutations/subscriptions); field names and types; exact error/toast copy in quotes; validation rules (required fields, formats, limits); loading/empty/error states with exact copy; accessibility attributes (roles, aria labels); permission model (which guards, which roles); state machines (status enums, transitions); known behaviours and bugs (with root cause when known).

Do NOT include: implementation advice or recommendations; inline source-code blocks; speculative future features; opinions on quality or design.

Structure per section: Overview (what it is, who uses it, where it lives) · Pages and routes table · Features (bulleted, grouped) · Interfaces (modals/drawers/panels/menus with field-level detail) · Interactions and logic (what happens on click/submit, sequencing) · States and validation · Permissions and visibility · Data and queryability (what durable records are produced, what the chat agent can answer) · Known behaviours.

Plain register — product-feature-guide.md + plain/*.md

Include: what the user sees (headings, buttons, lists, cards described visually); what happens when they interact (click, type, toggle, drag); what feedback they get (confirmations, warnings, errors in plain terms); empty/loading states in user terms; who can use it (roles in plain language); known quirks as user-observable behaviour.

Do NOT include: component names, file paths, route paths; GraphQL operations or API endpoints; field types, schema names, database details; technical root causes of bugs; accessibility attributes or aria labels; state-machine terminology; any word a non-developer would need to look up.

Style rules: second person ("you see", "you click"); say "pane/section/card/button/link", not "component/resolver/mutation"; describe errors as "a message appears saying…", not "renders an Alert with status=error"; no em dashes (use commas, full stops, or colons); no emojis; headings in sentence case.

Structure per section: Brief intro (what it is, who uses it, where it lives) · subsections by page or major feature · each subsection: Purpose · What you see · What you can do · States and feedback.

Quality checks (before a section is complete)

1. Accuracy — matches the live app / source. Planned-but-unreleased features are clearly marked as such.
2. Completeness — every interactive element, every state (loading/empty/error/success), every permission boundary.
3. No leaks — technical files carry no opinions; plain files carry no code terms.
4. Consistency — the same feature is described at the same scope across all four files. If the technical file says "6 segment options", the plain file also says 6.
5. Currency — when a ticket supersedes an earlier one (e.g. DIO-4761 superseded DIO-4760 on workflows), the earlier description is replaced, not accumulated alongside.

Done criteria

• The affected area's four files are updated (plus outbound-contact-surfaces.md if a contact/outbound surface changed).
• The technical pair agrees; the plain pair agrees; counts and names match across pairs.
• No UPDATE:/changelog residue; outdated content replaced.
• No register leaks (no code terms in plain files; no opinions in technical files).
• Plain files obey the style rules (second person, sentence-case headings, no em dashes, no emojis).
• Documentation reflects what actually shipped per the source-of-truth hierarchy, not just the ticket request.

Example invocations

update the marketing docs for DIO-4761

the inbox approval flow changed — refresh the feature docs for area 04

document the new survey distribution surface in the product docs (and outbound-contact-surfaces.md)

sync existing-features.md and the plain guide with what shipped on workflows

Source: DiologIR/diolog-plugins — distributed by TomeVault.