Using AI to Write Docs

This repository includes an AGENTS.md file at the root. It acts as a style guide for AI assistants — when you run your content through an AI tool with this file loaded, the output matches our docs standards for tone, structure, formatting, and components.

You write the technical content. The AI handles the editorial pass. The result is publish-ready documentation that reads like it belongs on the site.

What the AI does

The AGENTS.md file instructs the AI to act as a technical editor. It will:

Restructure your content for logical flow (prerequisites first, steps in order, intro at the top)
Rewrite sentences to be clear, direct, and active — matching the tone of docs like Cloudflare and Stripe
Convert paragraphs that describe sequential actions into numbered lists or <Steps> blocks
Add the standard page opening (H1, horizontal rule, intro description)
Format UI labels in bold, code in backticks, and expand acronyms on first use
Add components (<Callout>, <Tabs>, tables) where they improve readability
Flag anything unclear or missing rather than guessing

It will not invent content, remove technical detail, or add information that is not in your source material.

When to use this

Use this workflow when you have:

Raw notes, or specs you want to turn into a docs page
A rough draft that needs cleaning up for external readers
An existing page that does not match the site style and needs improvement

How it works

Write your content

Write however you like — bullet points, rough paragraphs, stream of consciousness. Do not worry about formatting, tone, or structure. Focus on getting the technical information down accurately and completely.

For example:

"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 wrong 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."

Run it through your AI tool

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

For new pages:

Using the AGENTS.md file as your style guide, turn this content into a docs page at pages/beam/how-to/configure-feed-source.mdx. Apply the full editorial pass. Do not add any information that is not in my notes.

For existing pages:

Using the AGENTS.md file as your style guide, restyle pages/beam/how-to/configure-feed-source.mdx. Apply the full editorial pass. Do not change any technical content.

For a batch of pages:

Using the AGENTS.md file as your style guide, restyle these pages. Apply the full editorial pass to each. Do not change any technical content.

pages/mkio/admin/teams.mdx

pages/mkio/admin/personal-tokens.mdx

If you spotted something specific:

Using the AGENTS.md file as your style guide, restyle pages/mkio/admin/teams.mdx. The "Edit projects" section is a wall of text that should be a numbered list. Apply the full editorial pass to the rest of the page too.

Review the output

The AI preserves your content but may misinterpret ambiguous phrasing. Always check:

Technical accuracy — every step, parameter, and detail is still correct.
Completeness — nothing was dropped. The AI flags anything unclear rather than guessing.
Tone — sentences sound natural and human, not robotic.

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 if my AI tool does not auto-discover AGENTS.md?

Some tools pick up AGENTS.md from the repo root automatically. If yours does not, add this to the start of your prompt:

Read the AGENTS.md file in the repository root before editing any documentation. Follow it as your style guide.

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

Tips

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 "this is a how-to" or "this is a reference page" helps the AI pick the right structure.
Specify the file path	Tell the AI exactly where the file should go so it uses the correct product terminology.
Review the intro	The AI will add an intro description under the H1. Make sure it accurately describes what the page covers.
Iterate	Ask the AI to refine specific sections — "make the intro shorter", "use a table here", "add a warning callout for the deletion step".