# Marketing Docs Maintenance > Keep the Diolog marketing/feature documentation set in docs/marketing/ current when a feature ships, a Linear ticket lands, or an area goes stale. Use this skill whenever the user asks to update, sync, refresh, or maintain the marketing docs / feature guide / product docs / feature documentation — e.g. 'update the marketing docs for DIO-1234', 'document this feature in the feature guide', 'the inbox docs are out of date', 'sync the product docs with what shipped', 'add this to existing-features.md', 'keep the feature documentation current' — or after implementing/changing a user-facing feature when the docs should follow. It updates the four-file set per area (features-build/final/XX-*.md + existing-features.md section 2.XX for technical detail; features-build/plain/XX-*.md + product-feature-guide.md section XX for plain language), plus outbound-contact-surfaces.md when a new contact/sharing/delivery surface is added. Enforces the content standards (technical files carry component names / routes / GraphQL ops - Skill: `tomevault-io/marketing-docs-maintenance` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/marketing-docs-maintenance` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/marketing-docs-maintenance/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/marketing-docs-maintenance --- # Marketing Docs Maintenance (Diolog) You maintain the Diolog marketing/feature documentation in `docs/marketing/`. When a feature ships or a Linear ticket lands, you bring the docs back into agreement with what the app actually does — editing the right area files, at the right detail level, with zero leakage between the technical and plain-language registers. The docs are a **record that follows the code**, never a specification that leads it. > **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/`: | File | Audience | Detail level | |------|----------|-------------| | `existing-features.md` | Engineers, AI agents, technical reviewers | **Full technical detail** — component names, GraphQL ops, route paths, state models, field names, validation rules, exact error/toast copy | | `features-build/final/XX-*.md` | Same as above (per-area working source) | **Full technical detail** — one file per area (01–19) | | `product-feature-guide.md` | PMs, customers, non-technical stakeholders | **Zero technical detail** — plain English: what users see and do | | `features-build/plain/XX-*.md` | Same as above (per-area working source) | **Zero technical detail** — one file per area (01–19) | | `outbound-contact-surfaces.md` | Product/design | Medium structured inventory of contact-input methods, delivery channels, options per surface | 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 | # | Area | Covers | |---|------|--------| | 01 | Auth | Login, sign-in, company picker, access denied | | 02 | Dashboard | Home screen, quick tools, regulatory updates, key metrics | | 03 | Chat | Conversations, agents, prompts, document picker, compliance canvas | | 04 | Inbox | Smart inbox, conversations, reply composer, approval flow | | 05 | Documents | Library, templates, editor, publishing, delivery metrics | | 06 | Calendar | Setup wizard, live view, calendar settings | | 07 | Disclosure | Disclosure consistency checker | | 08 | Perception | Perception studies | | 09 | Sentiment | Sentiment analyses | | 10 | Social | Monitoring (Investors tab, Competitors tab) | | 11 | Surveys | Survey creation, editor, publish, distribution, results | | 12 | Workflows | Library, intro page, run detail, step types | | 13 | Widgets | Admin studio, FAQ hub, embeddable widgets | | 14 | Portals | Public and private investor portals | | 15 | Settings | Settings modal (all 8 panes) | | 16 | Profile | User profile page | | 17 | Help | Help and support | | 18 | Admin | Admin console | | 19 | Cross-cutting | Behaviours spanning multiple areas | --- ## 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](https://github.com/DiologIR/diolog-plugins) — distributed by [TomeVault](https://tomevault.io).