Docs Authoring

Docs Authoring

Use this workflow for documentation PRs where the page needs to read like it belongs in the existing docs, land in the right navigation, include accurate supporting screenshots when useful, and ship with a clear PR description.

Workflow

1. Read the closest docs instructions first: repo AGENTS.md, docs-specific AGENTS.md, the docs navigation file, and 2-4 adjacent pages in the same section.
2. Match the existing docs exactly: frontmatter shape, title style, icon naming, heading depth, sentence length, callouts, screenshots, alt text, related links, and navigation placement.
3. Plan the docs change before writing: target reader, page goal, nav location, related pages, prerequisite state, and whether screenshots are needed.
4. Write the page in the existing style, then update navigation and adjacent links as needed.
5. Start the product stack only when real UI state is needed for screenshots or content verification. If the repo has cluster guidance, check for an existing stack before starting a new one.
6. Capture supporting product screenshots through Chrome DevTools. Do not use OS screenshots when the user asked for Chrome DevTools.
7. Hide Next.js dev UI before every capture. Re-run the suppression after navigation, reloads, or hot updates.
8. Consider an env-driven Next.js dev UI suppression path if the project already supports one, or if the user approves adding a local dev-only switch.
9. Add only documentation content screenshots to the repo. Save PR-only full-page docs screenshots in a local ignored artifact folder or /tmp, never in the commit unless the user explicitly asks.
10. Run the docs preview with mint, capture full-height screenshots of every added or materially changed docs page, and upload or link those screenshots in the PR description.
11. Create or update the PR with the appropriate docs label, usually documentation.
12. Verify the docs, git diff, screenshot links, labels, and PR body before calling the task done.

Tone And Style

Inspect existing pages before writing. Prefer the vocabulary and structure already in the section over introducing a new documentation voice.

Check for:

• Frontmatter fields and ordering.
• Whether pages use direct imperatives, conceptual explanation, or task steps.
• Heading capitalization and depth.
• Short paragraphs versus bullets.
• Screenshot placement and captions.
• Callout style and frequency.
• How Enterprise, beta, permissions, and related-page notes are phrased.

Keep the page focused on the user task. Avoid explaining UI that is already obvious from the screenshot, and avoid adding conceptual background if adjacent pages do not do that.

Docs Content

Write documentation as a product surface, not as implementation notes.

Before editing, identify:

• The exact user workflow or concept the page must support.
• Where the page belongs in the docs hierarchy.
• Whether the page should be task-oriented, conceptual, reference-style, or a mix, based on neighboring pages.
• Which screenshots, examples, callouts, or related links are expected by the existing section.

While writing:

• Use concrete product nouns and visible UI labels from the app.
• Prefer short, scannable sections with direct headings.
• Keep setup, permissions, Enterprise notes, and limitations phrased the same way adjacent pages do.
• Add screenshots only where they clarify state, placement, or a workflow step.
• Update navigation and related links in the same change.

Product Screenshots

Use Chrome DevTools or the available browser DevTools MCP to navigate the local app, set a stable viewport, seed realistic demo data when needed, and capture screenshots.

For Tracecat-style local work:

docker compose ls --filter name=tracecat
just cluster up -d
just cluster ps

Follow the repo's cluster instructions if they differ. Prefer existing service helpers such as just cluster logs, just cluster restart, and just cluster ports.

Screenshot rules:

• Capture the real UI state that the docs describe.
• Use stable filenames under the docs image directory, usually docs/img/<section>/<descriptive-name>.png.
• Embed committed screenshots from the docs page with clear alt text.
• Retake screenshots when overlays, loading states, scrollbars, toasts, or dev tools obscure the UI.
• Verify the image dimensions and file type with file or the browser screenshot metadata.

Hide Next.js Dev UI

Before screenshots, inject a temporary browser-session style/script through Chrome DevTools. Prefer this over cropping, manual UI hiding, or committed app code.

Use a snippet like this in the page context:

(() => {
  const id = "docs-screenshot-hide-next-dev-ui";
  document.getElementById(id)?.remove();

  const style = document.createElement("style");
  style.id = id;
  style.textContent = `
    nextjs-portal,
    [data-nextjs-dialog],
    [data-nextjs-dialog-overlay],
    [data-nextjs-toast],
    [data-nextjs-dev-tools-button],
    [data-nextjs-dev-tools-indicator],
    [aria-label="Open Next.js Dev Tools"],
    button[aria-label*="Next.js"],
    iframe[src*="nextjs"] {
      display: none !important;
      visibility: hidden !important;
      pointer-events: none !important;
      opacity: 0 !important;
    }
  `;
  document.documentElement.appendChild(style);
  document.querySelectorAll("nextjs-portal").forEach((el) => el.remove());
})();

After injecting it, visually inspect the page or take a quick screenshot to confirm the floating dev bubble is gone. If the dev UI reappears after navigation or hot reload, inject it again and retake the screenshot.

Only modify application source to suppress the dev UI if the user explicitly asks for a durable code change. Keep that change dev-only and reversible.

Env-Driven Suppression

Next.js supports hiding dev indicators through devIndicators: false in next.config.*; projects can also choose to drive that config from environment variables. Do not assume a universal Next.js env var exists. Inspect the project's Next.js version, next.config.*, package scripts, and local docs first.

If env-driven suppression is available or approved:

• Prefer a local, screenshot-session env var such as NEXT_HIDE_DEV_INDICATORS=1, DOCS_SCREENSHOT_MODE=1, or the project's existing equivalent.
• Wire it into next.config.* or dev-only UI code so it sets devIndicators: false or hides the custom devtools entry point only during local screenshot runs.
• Set it from the shell command, cluster env, or uncommitted .env.local; do not commit .env.local.
• Restart the Next.js dev server after changing env values.
• Reconfirm with Chrome DevTools that the floating dev bubble is gone before taking final screenshots.

Example pattern:

const hideDevIndicators =
  process.env.NEXT_HIDE_DEV_INDICATORS === "1" ||
  process.env.DOCS_SCREENSHOT_MODE === "1";

const nextConfig = {
  devIndicators: hideDevIndicators ? false : undefined,
};

module.exports = nextConfig;