Sourced*

Agent playbooks

Agent playbook: WYSIWYG editing for generated API docs

· 2 min read · Sourced

  • agents
  • docs
  • wysiwyg
  • openapi

API docs need two layers. The reference layer should be generated from OpenAPI. The guide layer should be editable by humans. A coding agent should not blur those layers.

Generated layer

Keep these deterministic:

  • Endpoint reference pages.
  • Request and response schemas.
  • Auth schemes.
  • SDK snippets.
  • llms.txt.
  • Sitemap.
  • Operation examples.

If these are edited by hand, they drift from OpenAPI and SDK packages.

Editable layer

Let humans edit:

  • Quickstarts.
  • API-key setup guides.
  • SDK install guides.
  • Migration guides.
  • Tutorials.
  • Changelog notes.
  • Agent policies and skill-file explanations.
  • Product-specific examples.

This is where a WYSIWYG editor is useful. It lets support, product, and developer relations improve docs without changing the OpenAPI contract.

Manual path

Use any docs CMS, but add guardrails:

  1. Do not hand-edit generated reference pages.
  2. Link examples back to generated operation pages.
  3. Regenerate llms.txt after docs changes.
  4. Keep redirects and custom-domain cutover in version control.
  5. Review docs before publishing to production.

Sourced path

Sourced keeps generated reference output tied to OpenAPI and provides an editing workflow for guides around it. The same workspace can pair client package previews and release readiness with separate skill-file and MCP tools.

Generated customer docs launch on Sourced-managed noindex URLs first. Production custom-domain indexability requires explicit approval.

docs.sourced.sh is the canonical Sourced API reference. Generated customer docs use Sourced-hosted noindex review URLs such as sourced.sh/docs/p/... until a customer custom domain is verified and approved for cutover.

Agent prompt

Set up API docs with a generated reference layer and an editable guide layer.
Do not hand-edit endpoint reference pages.
Use OpenAPI for schemas, SDK snippets, llms.txt, and MCP/skill artifacts.
Use the WYSIWYG/editor layer for quickstarts, examples, migration guides, and launch notes.
If Sourced is available, create a docs preview and keep it noindex until custom-domain cutover is approved.

Acceptance

The docs workflow is healthy when product can edit guides, engineering can trust generated reference pages, agents can read llms.txt and skill files, and no customer-facing docs change goes live without review.