Using AI to Write Docs

This site includes an AGENTS.md file at the repository root. It tells AI coding assistants how to convert raw technical content into polished, public-facing documentation - matching our style, structure, and component conventions.

The guide informs the AI to act as a technical editor, not an author. It will restyle and restructure what you give it, but it will never invent technical content.

When to Use This

This workflow is designed for engineers who have:

Internal notes or specs for a feature they want to turn into a docs page
A rough draft or brain-dump that needs to be cleaned up for external users
An existing page that does not match the site's style and needs reformatting

The AI handles the formatting, tone, and structure. You provide the technical truth.

How It Works

Step 1 — Write your raw content

Write your technical content however you like - bullet points, rough paragraphs, internal jargon, stream of consciousness. Do not worry about formatting, tone, or structure. Just get the information down.

For example, you might write something like:

"So basically the feed source needs to be configured with a valid ingest URL. The system checks the URL is reachable and then creates the feed object. If the URL is bad you get a 400. The user also needs to set the codec to either h264 or h265, and the container must be CMAF. After creating the feed source you need to start it before any segments come through."

Step 2 — Give it to the AI with your source material

Open the repo in your editor (VS Code, Cursor, etc.) and prompt the AI. Paste or reference your raw content and tell it where the page should live.

Example prompt:

"Here is my raw content for a new Beam how-to page. Convert it into a docs page at pages/beam/how-to/configure-feed-source.mdx following the AGENTS.md rules. Do not add any information that is not in my notes."

You can also point it at an existing file:

"Restyle pages/beam/how-to/configure-feed-source.mdx to match our docs conventions. Do not change or remove any technical content."

Step 3 — Review the output

The AI will restructure your content into the standard page template with proper headings, frontmatter, formatting, and components. Always review for:

Technical accuracy — the AI preserves your content but may misinterpret ambiguous phrasing. Check that every step, parameter, and detail is still correct.
Completeness — make sure nothing was accidentally dropped. The AI should flag anything unclear with  comments rather than guessing.
Tone — scan for anything that sounds off or too generic.

Step 4 — Commit and open a PR

Follow the normal contribution workflow:

Create a branch: docs/<short-description>
Commit: docs: <short summary>
Push and open a PR into main
Share the Vercel preview link with reviewers

What the AI Will Do

Restructure your content into the standard page template (frontmatter, H1, sections)
Rewrite to second person ("you"), present tense, active voice
Break long sentences into short ones
Expand acronyms on first use
Format UI labels in bold, code in backticks
Add numbered steps for sequential actions, bullets for unordered items
Add <Callout> components for warnings, notes, and important information
Use tables for structured reference data
Add  comments for anything that is unclear or missing

What the AI Will Not Do

Invent content, features, API endpoints, or steps that are not in your source material
Remove technical detail because it seems too complex
Add "helpful" filler that was not in your notes
Guess at anything it is unsure about

What If My AI Tool Does Not Auto-Discover AGENTS.md?

Some tools need a nudge. Paste this at the start of your prompt:

Read the AGENTS.md file in the repository root before editing any documentation. Do not invent or add any content that is not in the source material I provide.

Or, if your tool supports system instructions or custom rules, add that line there so it applies to every conversation.

Tips for Good Results

Tip	Why
Give it all the raw detail	The more technical information you provide, the better the output. The AI cannot look things up.
Mention the content type	Saying "write a how-to" or "write a reference page" helps the AI pick the right template.
Specify the file path	Tell the AI exactly where the file should go (e.g. `pages/beam/how-to/configure-feed-source.mdx`).
Name components you want	If you want a Callout, Cards grid, or WorkflowCard, say so — the AI knows the props.
Review TODO comments	If the AI was unsure about something, it will flag it with `<!-- TODO -->`. Answer those before merging.
Iterate	Ask the AI to "make the intro shorter", "add a prerequisites section", or "use a table instead of a list".