Skip to main content

产品文档撰写与排版规范

为了保证项目中各模块（如 监控系统、告警中心、CMDB 等）产品文档的风格统一、结构清晰，特制定此规范。后续生成或优化 spec/docs/ 目录下的文档时，请严格遵循以下准则。

1. 文档结构体系​

一个完整的核心模块产品文档，通常包含以下三个标准化文件（可根据模块复杂度进行增删）：

  • introduce.md（产品介绍）：侧重“是什么”与“为什么”。需包含「产品简介」、「核心优势」（总结概括）、「应用场景」（解决用户什么业务痛点）。
  • quick_start.md（快速入门）：侧重“怎么用”。提供从零到一的场景化接入/使用教程。需包含「前置条件」、「分步操作指引」、「结果验证与闭环」。
  • feature.md（核心功能介绍）：侧重“全貌拆解”。按产品核心导航模块（如 View、Search、Event 等）划分章节，详细展示每个子模块的「核心定位」与「核心能力」。

2. 写作排版规范​

2.1 标题层级​

  • H1 (#)：全篇唯一，作为文档的大标题（如 # 功能介绍）。
  • H2 (##)：作为模块级大类划分（如 ## 1. 监控视图 (View)）。
  • H3 (###) & H4 (####)：用于具体特性的拆解或步骤说明（如 ### 1.1 全局资源视图、#### 核心能力）。尽量避免超过4级的标题，以防阅读负担。

2.2 重点标注与符号​

  • UI 元素与状态：页面上的按钮、标签页、关键状态词，请使用「」或 粗体 标准（例如：点击「+接入」按钮，或选择 严重 (Fatal) 级别）。
  • 英文术语与代码：系统涉及的英文专有配置（如 Labels、Tags）或字段代码，请使用格式符包裹（如 no_data_alert）。

2.3 核心能力写法​

在 feature.md 描述具体功能时，必须采用 列表形式 提炼“核心能力”，要求语句结构：**特性名称**：特性描述（解决什么问题）。

示例：

  • 多维分类导航：左侧支持按「操作系统、网络」等维度筛选纳管对象，快速定位资产。

3. 图文与提示块标准​

3.1 界面图文指引​

为避免单纯放一张图导致重点模糊，所有的截图引用必须使用块引用嵌套，并提供“界面指引”解读。

> ** 界面指引：**
> 
> ![图表名称](https://static.../xxx.png)
> 
> *   **图表解读/配置逻辑**：在此处用一两句话解释图中圈出的高关注点（如：波峰过高说明什么，下拉框里应该填什么）。

3.2 总结与风险提示​

对于涉及安全、高危操作或特别说明项，使用醒目的引用块标识：

> ** 注意 / 安全最佳实践：**
> 避免使用 root 账号，请创建低权限只读用户。

4. 行文语调与理念​

  1. 用户视角闭环：不仅教用户“如何配置”，还要告诉用户配置后“去哪里看效果”，以及异常时“如何形成风险闭环”（例如配置完采集后，一定要写去 View 层验证数据，并建议去 Event 层配置告警）。
  2. 去技术化与价值呈现：面向最终使用者的文档必须避免陷入“研发自嗨”。应将诸如 TraceID、Stdout 等技术术语翻译为面向用户的场景化白话。强调产品在帮用户解决什么痛点（Why），而非枯燥地描述技术实现细节（How）。：避免过度口语化、文学化辞藻，保持 B 端企业级产品的专业性与干练。
  3. 防脑补与严格对齐代码事实：绝不可凭开源经验臆造功能或前端组件结构。下笔前必须核查现网 UI 代码与 Changelogs。必须做到“所见即所得”，不存在的功能（如并不存在的画板拖拽组合等）严禁写入。