ark-documentation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseArk Documentation
ARK文档
Guidance for structuring Ark documentation using Diataxis adapted for Ark's needs.
适配ARK需求的、使用Diataxis框架构建ARK文档的指南。
When to use this skill
何时使用本方法
- Creating new documentation
- Deciding where content belongs
- Reviewing documentation PRs
- Restructuring existing documentation
- 创建新文档
- 确定内容归属
- 评审文档PR
- 重构现有文档
ARK's Diataxis structure
ARK的Diataxis结构
docs/content/
├── Introduction
├── Quickstart
├── Tutorials → Linear learning paths
├── How-to Guides → Task-oriented, by persona
├── Core Concepts → Understanding "why" and "how"
├── Reference → Factual lookup material
├── Marketplace → External link
└── Disclaimerdocs/content/
├── Introduction
├── Quickstart
├── Tutorials → Linear learning paths
├── How-to Guides → Task-oriented, by persona
├── Core Concepts → Understanding "why" and "how"
├── Reference → Factual lookup material
├── Marketplace → External link
└── DisclaimerTerminology
术语
| Diataxis | Ark Term | Why |
|---|---|---|
| Explanation | Core Concepts | More accessible |
| Diataxis术语 | ARK术语 | 原因 |
|---|---|---|
| Explanation | Core Concepts（核心概念） | 更易于理解 |
The four quadrants
四个象限
1. Tutorials (learning-oriented)
1. 教程（以学习为导向）
Purpose: Hands-on lessons for newcomers.
Characteristics:
- Linear, numbered paths (1, 2, 3...)
- Single prescribed path - no choices
- Frequent visible results
- Ends with "Next step" → How-to Guides
Writing style:
- Use "we" language
- Don't explain - link to Core Concepts
Content belongs here if:
- It teaches a skill through doing
- Reader is studying, not working
- Success requires following steps in order
Examples: Quickstart, Running the Dashboard, Starting a New Project, Complete Worked Example
目的：为新手提供实操课程。
特点:
- 线性、分步骤的路径（1、2、3...）
- 单一指定路径，无选择分支
- 频繁呈现可见成果
- 结尾引导至“下一步” → 操作指南
写作风格:
- 使用“我们”的口吻
- 不做解释，链接至核心概念
内容归属判断:
- 通过实操教授技能
- 读者处于学习阶段，而非工作场景
- 需按顺序遵循步骤才能成功
示例：快速入门、运行控制台、启动新项目、完整实操案例
2. How-to guides (task-oriented)
2. 操作指南（以任务为导向）
Purpose: Help competent users complete specific tasks.
Organized by persona:
目的：帮助熟练用户完成特定任务。
按用户角色分类:
Build with ARK (application developers)
基于ARK构建（应用开发者）
- Configure models, create agents, coordinate teams, run queries, add tools.
- 配置模型、创建Agent、协调团队、运行查询、添加工具。
Extend ARK (contributors)
扩展ARK功能（贡献者）
- Build services locally, implement APIs, build A2A servers, add tests.
- 本地构建服务、实现API、搭建A2A服务器、添加测试。
Operate ARK (operators / SRE / security)
运维ARK（运维人员/SRE/安全人员）
- Platform operations: Provisioning, deploying
- CI/CD and supply chain: Build pipelines
- Security & assurance: Pen testing, code analysis
Writing style:
- Goal-oriented: "If you want X, do Y"
- Assumes competence
- Don't teach - link to Tutorials or Core Concepts
Content belongs here if:
- Reader has a specific task to complete
- Reader is working, not studying
- 平台运维：资源配置、部署
- CI/CD与供应链：构建流水线
- 安全与保障：渗透测试、代码分析
写作风格:
- 目标导向：“如果您想实现X，请执行Y”
- 假设读者具备相关能力
- 不教授基础知识，链接至教程或核心概念
内容归属判断:
- 读者需完成特定任务
- 读者处于工作场景，而非学习阶段
3. Core concepts (understanding-oriented)
3. 核心概念（以理解为导向）
Purpose: Explain what ARK is, how it's designed, and why.
Topics:
- What ARK is and how it works.
- Design effective agentic systems.
- Platform architecture concepts.
- Extensibility concepts.
- Security and identity concepts.
Writing style:
- Discursive: "The reason for X is..."
- Make connections between concepts
- Provide design decision context
Content belongs here if:
- It answers "why" or "how does this work"
- Reader is deciding how to design/extend/operate
- Content provides context, not procedures
目的：解释ARK是什么、设计原理及原因。
涵盖主题:
- ARK的定义与工作原理。
- 设计高效的Agent系统。
- 平台架构概念。
- 可扩展性概念。
- 安全与身份认证概念。
写作风格:
- 论述式：“X的原因是...”
- 建立概念间的关联
- 提供设计决策的背景
内容归属判断:
- 解答“为什么”或“如何运作”的问题
- 读者正决定如何设计/扩展/运维
- 内容提供背景信息，而非操作步骤
4. Reference (information-oriented)
4. 参考资料（以信息查询为导向）
Purpose: Factual lookup material.
Organized by type:
- Interfaces: ARK APIs.
- Kubernetes API: CRDs, resources.
- Evaluations: Guides, event-based evaluations.
- System behavior: Query execution, relationships.
- Operations: Upgrading, troubleshooting.
- Project: Contributors.
Writing style:
- Austere, factual, neutral
- Structure mirrors product
- No instruction, explanation, or opinion
Content belongs here if:
- It describes what something IS
- Reader needs to look up specific details
- Content is consulted, not read cover-to-cover
目的：供查阅的事实性资料。
按类型分类:
- 接口：ARK API。
- Kubernetes API：CRD、资源。
- 评估：指南、基于事件的评估。
- 系统行为：查询执行、关系。
- 运维：升级、故障排查。
- 项目：贡献者。
写作风格:
- 简洁、事实性、中立
- 结构与产品一致
- 无指令、解释或主观观点
内容归属判断:
- 描述事物的本质
- 读者需要查阅特定细节
- 内容用于查阅，而非通读
Decision guide
决策指南
Is the reader LEARNING or WORKING?
│
├─ LEARNING (studying)
│ ├─ Hands-on, step-by-step? → TUTORIALS
│ └─ Understanding concepts? → CORE CONCEPTS
│
└─ WORKING (applying)
├─ Completing a task? → HOW-TO GUIDES
└─ Looking up facts? → REFERENCEIs the reader LEARNING or WORKING?
│
├─ LEARNING (studying)
│ ├─ Hands-on, step-by-step? → TUTORIALS
│ └─ Understanding concepts? → CORE CONCEPTS
│
└─ WORKING (applying)
├─ Completing a task? → HOW-TO GUIDES
└─ Looking up facts? → REFERENCEHub pages
枢纽页面
Hub pages link to content without moving files:
- - Lists tutorials in order.
tutorials.mdx - - Groups by persona.
how-to-guides.mdx - - Groups by topic.
core-concepts.mdx - - Groups by type.
reference/index.mdx
Hub pages should:
- Explain purpose in one sentence.
- Group links logically.
- Not duplicate content.
枢纽页面仅链接内容，不移动文件：
- - 按顺序列出所有教程。
tutorials.mdx - - 按用户角色分组。
how-to-guides.mdx - - 按主题分组。
core-concepts.mdx - - 按类型分组。
reference/index.mdx
枢纽页面需满足：
- 用一句话说明用途。
- 逻辑化分组链接。
- 不重复内容。
Personas
用户角色
| Persona | Sections |
|---|---|
| End users | Quickstart, Tutorials |
| Agent builders | Tutorials, How-to (Build) |
| Platform engineers | How-to (Operate), Reference |
| Contributors | How-to (Extend), Core Concepts |
| 用户角色 | 对应板块 |
|---|---|
| 终端用户 | 快速入门、教程 |
| Agent构建者 | 教程、操作指南（构建） |
| 平台工程师 | 操作指南（运维）、参考资料 |
| 贡献者 | 操作指南（扩展）、核心概念 |
Writing guidelines
写作指南
Lexicon
术语表
- The product is known as ARK rather than Ark.
- 产品名称统一为ARK，而非Ark。
General style
通用风格
- Be concise and direct.
- Use simple language.
- Keep descriptions to 1-2 sentences.
- Use active voice: "Creates agent" not "Agent is created".
- Write "ARK" not "Ark".
- Use US English.
- Use Oxford commas in lists.
- 简洁直接。
- 使用简单语言。
- 描述控制在1-2句话内。
- 使用主动语态：“创建Agent”而非“Agent被创建”。
- 统一写“ARK”而非“Ark”。
- 使用美式英语。
- 列表中使用牛津逗号。
Bullets
列表
- Capitalize the first word and end with a period.
- Use numbered lists only for sequences of instructions or when referencing items later.
- 首字母大写，结尾加句号。
- 仅在指令序列或后续需引用列表项时使用编号列表。
Capitalization
大小写规范
- Capitalize only proper nouns (product names, tools, services).
- Use sentence case for titles: "An introduction to data visualization" not "An Introduction to Data Visualization".
- Don't capitalize: cloud, internet, machine learning, advanced analytics.
- 仅大写专有名词（产品名、工具、服务）。
- 标题使用句子式大小写：例如写“An introduction to data visualization”而非“An Introduction to Data Visualization”。
- 以下词汇不大写：cloud、internet、machine learning、advanced analytics。
Headings
标题
- Avoid gerunds: "Get started" not "Getting started," "Customize a layout" not "Customizing a layout".
- Keep titles short and descriptive for search discoverability.
- 避免使用动名词：写“快速入门”（Get started）而非“Getting started”，写“自定义布局”（Customize a layout）而非“Customizing a layout”。
- 标题应简短且具描述性，以提升搜索可发现性。
Instructions
指令
- Use imperatives: "Complete the configuration steps".
- Don't use "please".
- Don't use passive tense: "Complete the steps" not "The steps should be completed".
- 使用祈使句：“完成配置步骤”。
- 不使用“请”。
- 不使用被动语态：“完成步骤”而非“步骤应被完成”。
Links
链接
- Make hyperlinks descriptive: .
Learn how to [contribute to ARK](url) - Don't write: .
To contribute, see [here](url)
- 超链接需具描述性：例如。
了解如何[为ARK做贡献](url) - 避免写法：。
如需贡献，请查看[此处](url)
Avoid
需避免的内容
- Gerunds in headings.
- Colloquialisms (may not translate across regions/languages).
- Business speak: "leverage", "utilize", "facilitate".
- 标题中使用动名词。
- 口语化表达（可能无法跨地区/语言翻译）。
- 商务话术：“leverage”、“utilize”、“facilitate”。
What not to mix
内容混排禁忌
| Don't put in... | This content... |
|---|---|
| Tutorials | Explanations, choices. |
| How-to guides | Teaching, complete reference. |
| Core concepts | Instructions, reference. |
| Reference | Instructions, explanations. |
| 请勿放入... | 此类内容... |
|---|---|
| 教程 | 解释性内容、选择分支。 |
| 操作指南 | 教学内容、完整参考资料。 |
| 核心概念 | 指令、参考资料。 |
| 参考资料 | 指令、解释性内容。 |