# Writing Docs with AI \[Use an AI agent to create and maintain Vocs documentation] Vocs is designed to work well with AI agents. The best results come from giving the agent a clear docs task, the Vocs guides it should read, the files it should edit, and the command it should run to verify the site. ## Start with a Prompt For a new docs site, ask your agent to read the Getting Started guide first: ```txt Read https://vocs.dev/introduction/getting-started and set up Vocs for my project. ``` For an existing project, give the agent a tighter task: ```txt Read https://vocs.dev/introduction/getting-started, https://vocs.dev/introduction/project-structure, and https://vocs.dev/writing/markdown-extensions. Then audit this project and add Vocs documentation. Edit the docs source files, update navigation, and run the docs build when you are done. ``` ## Files Agents Usually Edit | File | Purpose | | --- | --- | | `vocs.config.ts` | Site title, description, navigation, integrations, and theme config. | | `src/pages/**/*.md` | Markdown-only documentation pages. | | `src/pages/**/*.mdx` | Documentation pages that use imports, JSX, or Vocs components. | | `src/pages/_root.css` | Global docs styles and theme token overrides. | | `public/**` | Static assets such as logos, images, favicons, and fonts. | Ask agents to avoid generated files, build output, and unrelated application code unless the docs task explicitly requires them. ## Add a Page When asking an agent to add a page, include the route, audience, and outcome: ```txt Add a Vocs page at src/pages/guide/authentication.mdx for developers integrating authentication. Explain the happy path first, include one minimal code example, add a troubleshooting section, and add the page to the sidebar. ``` For pages that should work well in `llms.txt`, ask for clear headings and a short description: ```txt Use a descriptive H1 with bracketed subtext, keep sections task-based, and avoid placeholder examples. ``` ## Update Navigation Vocs navigation lives in `vocs.config.ts`. When an agent adds, removes, or renames pages, ask it to update the sidebar in the same change. ```txt After creating the page, update the Vocs sidebar so the new route appears in the right section. ``` ## Verify the Result End every docs prompt with a verification step. The exact command depends on your package manager and scripts, but most Vocs projects expose a build script. ```txt Run the docs build, fix any broken links or MDX errors, and tell me the local URL I can open. ``` If the agent changes code examples, ask it to check that imports, filenames, and snippet paths match the project. ## Useful Follow-Up Prompts ```txt Audit these docs as if you are a first-time developer using this SDK. List missing pages, unclear examples, and navigation problems. ``` ```txt Rewrite this page to be easier for an AI agent to retrieve. Keep headings task-based, add a concise description, and remove placeholder examples. ``` ```txt Find code examples in the docs that do not match the current source code and update them. ```