Skip to main content
KEEP THIS ULTRA SIMPLE: This document is context for other AI agents. Do NOT add extra content, explanations, or “waffle”. Only include the absolute minimum commands needed.
DOUBLE HEADING BUG: MDX files automatically generate H1 from the title. Do NOT add a second H1 heading or you’ll get duplicate headings in the rendered page.

​
Writing Principles

​
One Concept Per Page

Each user manual page should focus on one single concept only. Never combine multiple concepts in a single page.

​
Simple Titles and Descriptions

  • Title: Simple action-focused titles - DO NOT include “How to”
  • Description: Use simple, clear language - avoid “comprehensive” or overly complex descriptions
  • No Double Headings: Don’t add H1 (#) after the frontmatter title

​
Content Structure

  • Use clear subheadings to organize content
  • Break down complex processes into simple steps
  • Keep explanations minimal and focused

​
Examples

Good: “Add Team Members” Bad: “How to Add Team Members” or “Team Management and User Roles” Good: “Log In” Bad: “How to Log In” or “Logging Into Your Account” Good Description: “Step-by-step guide to invite team members” Bad Description: “Comprehensive user manual for inviting and managing team members”

​
Page Structure Rules

​
NEVER Include These Sections:

  • Overview - The title and description already explain what the page does
  • Introduction - The description is the introduction
  • Before You Start - If they’re on the page, they want to do the task
  • Prerequisites - Only include critical warnings inline where needed
  • Introduction paragraphs - Keep opening content minimal
  • Getting Started - Jump straight to the steps
  • Opening sentences that repeat the title/description - No waffle at the top

​
ALWAYS Follow This Structure:

For Simple Single-Concept Pages:
WRONG - Never do this:
For Complex Multi-Section Pages:

​
When to Use Section Headings:

  • Use section headings only when you have multiple distinct groups of steps
  • Skip section headings for simple, single-concept workflows
  • Don’t add headings just because you think you need them

​
Section Heading Rules:

  • NO “Step-by-Step Process” - the description already says it’s step-by-step
  • NO “Getting Started” or similar generic headings
  • Use descriptive action names like “Access User Management”, “Send Invitation”, “Configure Settings”
  • Be specific about what the section accomplishes
  • Never repeat words from the title or description

​
Examples of Good Section Headings:

  • “Access User Management”
  • “Send Invitation”
  • “Configure Role Permissions”
  • “Navigate to Settings”
  • “Complete Profile Setup”

​
Examples of Bad Section Headings:

  • “Step-by-Step Process”
  • “How to Get Started”
  • “Follow These Steps”
  • “Process Overview”

​
NO WAFFLE RULE:

  • Start immediately with the first section heading or Steps
  • Never repeat what’s already in the title or description
  • No “Overview” sections - The description IS the overview
  • No opening sentences like “This guide will show you…” or “Follow these steps…”
  • No permission statements like “You’ll need Admin permissions” - put these in warnings inside steps if critical
  • Jump straight to the content - the title and description already explain what the page does

​
Inline Warnings Only

  • Put warnings INSIDE the relevant step
  • Only warn about critical issues that would cause problems
  • Don’t warn about obvious things (like “make sure you want to do this”)

​
Essential Process

​
1. Setup Environment

​
2. Configure Browser

​
3. Navigate & Screenshot

​
4. User Actions

​
5. Two-Factor Authentication Handling

SECURITY REQUIREMENT: Never attempt to bypass 2FA or use test codes. Always complete the proper authentication flow.
When 2FA verification screen appears:
  1. STOP and ask the user for the current 2FA code
  2. WAIT for the user to provide the 6-digit verification code
  3. NEVER attempt to bypass or skip 2FA verification
  4. ALWAYS use the code provided by the user
Proper 2FA workflow:

​
6. Copy Screenshots

​
7. Verify Files

​
Image References in MDX

​
Test Credentials

​
File Structure

​
Key Commands Only

  • mcp_playwright_browser_navigate - Go to URL
  • mcp_playwright_browser_resize - Set browser size
  • mcp_playwright_browser_take_screenshot - Capture screen
  • mcp_playwright_browser_type - Fill form fields
  • mcp_playwright_browser_click - Click elements
  • mcp_playwright_browser_wait_for - Wait for loading
  • cp - Copy screenshots to docs folder

​
Final Review Checklist

CRITICAL: Before completing any documentation task, review ALL created files and verify:

​
Content Structure Review

  • No “Overview” sections - Does the content jump straight to steps or section headings?
  • No waffle - Are there any opening sentences that repeat the title/description?
  • No double headings - Is there any repetition between title/description and content?
  • No permission statements - Are admin requirements mentioned as waffle instead of inline warnings?

​
Page Structure Review

  • Title follows rules - Simple action, no “How to” prefix
  • Description is simple - No “comprehensive” or overly complex language
  • Section headings are specific - No generic headings like “Getting Started”
  • Steps are clear - Each step has a clear action and screenshot

​
Common Violations to Fix

  • “Overview” sections → DELETE immediately
  • “This guide shows…” → DELETE immediately
  • “You’ll need Admin permissions” → Move to inline warning if critical
  • “Before You Start” → DELETE or move to inline warnings
  • Generic section headings → Make specific and action-focused
If any violations are found, fix them immediately before delivery.