Document all providers that support a feature with examples — ensures complete coverage and discoverability for users — Users may miss provider support if docs only show partial examples, leading to incorrect assumptions about feature availability
Link to provider docs for model lists and features — prevents stale info when providers update their offerings — External provider catalogs change frequently; linking to authoritative sources keeps docs accurate without maintenance burden
Link to existing docs/API refs instead of re-explaining concepts — reduces duplication and keeps info in sync — Prevents documentation drift and outdated explanations by maintaining a single source of truth for each concept
Keep feature docs provider-agnostic; put provider-specific details in dedicated provider sections — Prevents duplication and makes docs easier to maintain when shared parameters change across providers
Link to canonical docs rather than duplicating content — prevents drift and maintenance burden — Consolidating documentation into existing files with cross-references keeps information consistent and reduces the effort needed to update multiple locations when changes occur.
Document only public APIs and user-facing behavior — exclude internals, framework abstractions, and implementation plumbing — Users need actionable documentation on what they can use, not confusing details about internal mechanics they can't control
Explain before showing — place explanatory text before code examples, not after — Users need context to understand code examples; "explain then show" improves comprehension and reduces confusion
Use 'Pydantic AI' (with space) in prose — ensures consistent brand identity — Maintains professional brand consistency across all documentation and prevents confusion with variations like 'Pydantic-AI', 'PydanticAI', or 'pAI'
Create dedicated pages for substantial features — ensures discoverability and comprehensive coverage vs. fragmented mentions — Prevents users from missing features when they approach from different contexts (CLI vs. API) and allows features to be documented holistically rather than buried in subsections.
Avoid # ruff: noqa or # type: ignore in doc examples — ensures examples stay correct and runnable — Skip directives hide bugs and type errors in documentation code that users will copy, leading to broken examples in the wild
Explicitly mark parameters/features as 'optional' in docs, even when types show it — reduces cognitive load for readers — Users shouldn't need to parse type signatures to understand optionality; explicit labels make documentation scannable and accessible to all skill levels
Remove documentation sections explaining standard behavior that "just works" — keeps docs focused on actionable, non-obvious information — Users don't need explanations of things that work automatically; documentation should focus on configuration requirements, edge cases, and non-obvious behaviors that affect usage decisions
Strip boilerplate from docs examples — show only the feature being demonstrated — Reduces cognitive load and helps readers focus on the specific API or pattern being taught without distraction from scaffolding code.
Always include provider prefixes in model name examples (e.g., openai:gpt-5.2, anthropic:claude-opus-4-5) — Teaches users the correct format and prevents runtime errors from missing provider context