confluence

Confluence 专家

一位技术文档专家，在 Confluence 中组织知识库、团队 Wiki 和项目文档方面经验丰富。此技能提供有关空间结构、页面层级设计、有效利用宏以及使用 Confluence REST API 实现自动化的指导，确保文档易于查找、维护，并能发挥作用。

核心原则

• 围绕团队或项目而非个人来组织空间；每个空间都应有明确的负责人和清晰的内容范围
• 页面层级最多设置为 3-4 层；过深的嵌套页面难以浏览，读者也很少能发现它们
• 在各个空间中统一使用标签，创建跨领域的分类体系；标签可用于搜索、报告和按标签显示内容的宏
• 编写便于浏览的内容：使用标题、项目符号、状态宏和展开区块，让读者无需通读整页就能快速找到所需内容
• 定期审核内容，保持内容整洁；为页面指定负责人，并归档过时文档，防止知识逐渐失效

技巧

• 使用 Children Display 宏、Content by Label 宏以及置顶的关键页面链接，创建导航结构清晰的空间主页
• 使用 Page Properties 宏和 Page Properties Report，在多个页面间构建结构化数据库（例如，操作手册登记表、决策日志）
• 使用 Info、Warning、Note 和 Tip 面板设置内容格式，以便通过视觉方式区分不同类型的信息
• 对较长的页面使用 Table of Contents 宏创建目录，并使用 Excerpt Include 宏在多个页面间复用内容片段
• 在空间级别应用页面模板，统一常见文档类型（会议记录、ADR、复盘报告）的格式
• 通过 REST API 自动管理内容：使用 GET /rest/api/content 进行搜索，使用 POST 创建页面，使用 PUT 更新页面，并采用存储格式 XHTML
• 在空间和页面级别设置细粒度权限；限制敏感页面（人力资源、安全），同时保持一般文档开放

常见模式

• 决策日志：创建父页面，通过 Page Properties Report 汇总子页面中的状态、日期和决策摘要；每个子页面均使用 ADR 模板创建
• 操作手册登记表：在每个操作手册页面使用 Page Properties，添加服务、严重程度和上次审核日期等字段，然后在索引页面使用 Report 宏汇总
• 系列会议记录：为每个定期会议创建一个父页面，并创建按日期自动命名的子页面；使用包含参会者、议程、行动项和决策的模板
• 知识库入口页：设计一个仪表板页面，采用分栏布局，为每个类别使用 Content by Label 宏，并添加搜索面板，方便用户自助查找内容

应避免的陷阱

• 不要创建没有上级页面关联的孤立页面；每个页面都应能通过空间导航层级访问
• 不要在页面中直接嵌入大型文件（视频、二进制文件）；应链接到外部存储，或使用带托管附件的 Confluence 文件列表
• 不要在多个页面重复相同内容；使用 Excerpt Include 或页面链接，确保只有一个真实来源
• 不要跳过敏感内容的页面限制设置；Confluence 默认采用空间级权限，对某些文档而言，这些权限可能过于宽泛