Documentation Update Principles
Languages: English · 中文
Agently public technical documentation uses the main repository docs/ as the shared source of truth. The website can own visual design, navigation, homepage, customer presentation, and marketing pages, but technical body content, version facts, recommended usage, code examples, deprecation notes, and release explanations should land in the main repository first.
The benefit is simple: when a framework version changes, code, examples, compatibility metadata, Agently-Skills, and the website do not drift into separate stories.
Source Ownership
| Location | Owns | Does not own |
|---|---|---|
Main repo docs/cn, docs/en | Technical source: capability docs, usage guidance, code examples, scenario playbooks, release notes, deprecation/version notes | Website visuals, homepage animation, customer showcase, static marketing pages |
| Website VitePress | Presentation of main-repo docs: navigation, sidebar, SEO, dual-domain routing, search, styles, link checks | A private second copy of technical facts |
| Website homepage and marketing pages | Product positioning, value narrative, customer cases, careers, trademark/license statement | Replacing main-repo technical docs |
| Agently-Skills | Current recommended path, project structure, and validation guidance for coding agents | The only runtime API documentation source |
The website may organize navigation by reader path, but technical body content should be synchronized from the main repository. If a technical page needs website-style rewriting, rewrite it in the main repository, then sync.
After Each Release
| Change type | Must check |
|---|---|
| New API / capability | Capability page, quickstart or playbook, examples, release notes, capability map |
| Recommended usage change | Getting-started path, snippets, Agently-Skills, migration guidance |
| Behavior change | Usage notes, boundary cases, error semantics, compatibility notes, tests or example output |
| Deprecation or downgraded path | Deprecation note, migration path, whether old API is removed from new-user route |
| Provider / model config change | Model setup, quickstart, compatible protocol notes, example config |
| Runtime / streaming / observability change | Model Response, TriggerFlow, DevTools, service docs |
Before merging docs, confirm:
- Code and examples show the same usage that the docs recommend.
- Release notes explain the version fact and migration impact.
- Website sync has no broken links, duplicate pages, or stale entrypoints.
Writing Principles
Public docs are not API dictionaries. Readers usually arrive with a business problem, then look for the API.
| Principle | Writing shape |
|---|---|
| Open with a scenario, not a definition | Start from the problem the reader faces, then show which engineering chain Agently fills |
| Problem before solution | Show concrete costs such as drifting output, uncontrolled tools, unrecoverable workflows |
| Reader-benefit framing | Explain what the reader gains or avoids; avoid moralizing rules |
| Judgment-based headings | "When to use TriggerFlow" is more useful than "TriggerFlow introduction" |
| Facts first | Prefer code, examples, release notes, and project evidence over generic promotion |
| Downgrade old paths | Compatibility APIs may remain, but should not be the first path for new users |
Avoid:
- Dramatic closing lines such as "this is the real value of X".
- Condescending commands such as "this is engineering discipline, not advice".
- Abstract value claims without showing how the reader benefits.
- Long uninterrupted concept dumps without tables, diagrams, tips, code, or checklists.
Combining Diagrams, Tables, Tips, and Code
Core pages should usually include more than prose.
| Content type | Good for |
|---|---|
| Tables | Capability boundaries, selection decisions, version differences, mistakes and fixes, launch checks |
| Diagrams / Mermaid | Request chain, TriggerFlow lifecycle, service topology, state transitions |
| Tips / warnings | Key mistakes, compatibility notes, safety boundaries, launch reminders |
| Code blocks | Recommended API shape, minimal runnable snippet, before/after migration |
| Checklists | Release review, pre-launch acceptance, playbook implementation |
Code blocks must reflect real usage. Do not include snippets that cannot run, are simplified into a misleading shape, or exist only to show syntax. Examples that claim model-owned behavior should use real DeepSeek or local Ollama when feasible; if an external system is mocked, state that boundary.
Page Structure
Capability pages should usually follow:
- Scenario problem: when to read this page.
- Minimal recommended usage: code or flow.
- Capability boundary: what it owns and does not own.
- Upgrade path: when to add Actions, Workspace, TriggerFlow, Dynamic Task.
- Common misuse: wrong pattern, consequence, correction.
- Version and compatibility notes.
- Next reading based on the reader's next task.
Playbook pages should usually follow:
- Business scenario and deliverable.
- Recommended architecture or flow.
- Structured output or state contract.
- Agently capabilities involved.
- UI / service / workflow / evidence integration.
- Acceptance checklist.
- Continue reading.
Bilingual Sync
The main repository should maintain real docs/cn and docs/en source documents. English pages should not be only Chinese mirrors. If only Chinese can be finished first, mark the English page as pending translation instead of presenting it as complete English content.
Update order:
- Complete Chinese facts and structure.
- Write English with the same facts, boundaries, code, and version notes; it does not need to be word-for-word translation.
- Sync the website from the main repository; do not edit technical body copy only in the website repo.
Completion Check
| Check | Passing standard |
|---|---|
| Fact source | Traceable to code, examples, release notes, spec, or project evidence |
| Recommended path | New-user routes do not recommend deprecated or compatibility APIs |
| Code example | Matches current API and is run or points to a validated example when needed |
| Scenario framing | Reader knows what problem the page solves |
| Presentation | Uses tables, flow, tips, code, or checklists instead of only long prose |
| Bilingual | Chinese and English facts match; links work |
| Website sync | VitePress build, link check, and sitemap generation pass |