Zulip项目集成开发文档编写指南

Zulip项目集成开发文档编写指南

zulip Zulip 服务器和Web应用程序。开源团队聊天工具，帮助团队保持生产力和专注度。 项目地址: https://gitcode.com/gh_mirrors/zu/zulip

前言

Zulip作为一款优秀的开源团队协作工具，其强大的集成能力是其核心优势之一。本文将详细介绍如何为Zulip项目编写高质量的集成文档，帮助开发者更好地为各种第三方服务创建集成方案。

文档结构概述

Zulip集成文档采用Markdown格式编写，主要分为两种类型：

1. Webhook集成文档：位于zerver/webhooks/{webhook_name}/doc.md
2. 非Webhook集成文档：位于templates/zerver/integrations/{integration_name}.md

文档编写流程

1. 编写集成说明

首先需要详细描述集成的设置步骤，包括：

• 所需的URL配置
• 第三方服务的具体操作步骤
• 必要的参数设置

建议参考已有集成文档（如Basecamp集成）的格式和风格。

2. 注册集成配置

需要在zerver/lib/integrations.py文件中添加集成信息：

• 在WEBHOOK_INTEGRATIONS或INTEGRATIONS部分注册
• 在DOC_SCREENSHOT_CONFIG部分配置截图生成

3. 添加集成图标

需要准备集成服务的SVG格式logo：

• 存放路径：static/images/integrations/logos/<name>.svg
• 使用tools/setup/optimize-svg工具优化SVG文件
• 如果没有SVG格式，可使用PNG格式替代

4. 生成示例消息截图

对于Webhook集成，可使用以下命令生成截图：

./tools/screenshots/generate-integration-docs-screenshot --integration integrationname

也可以手动生成截图，注意：

• 为测试机器人设置合适的名称（如"GitHub Bot"）
• 使用项目logo作为机器人头像
• 截图应包含消息的频道/主题栏

Markdown宏使用指南

Zulip提供了一系列Markdown宏来简化文档编写，这些宏位于templates/zerver/integrations/include/目录下。

常用宏介绍

1. 创建频道宏 {!create-channel.md!}

   • 建议用户为集成创建专用频道
   • 通常是设置步骤的第一步

2. 创建Webhook机器人宏 {!create-an-incoming-webhook.md!}

   • 指导用户创建Webhook类型的机器人
   • 通常紧随创建频道宏之后

3. 创建通用机器人宏 {!create-a-generic-bot.md!}

   • 指导用户创建通用类型的机器人

4. 生成Webhook URL宏 {!generate-webhook-url-basic.md!}

   • 指导用户获取机器人URL
   • 不应与创建频道宏同时使用

5. 生成集成URL宏 {!generate-integration-url.md!}

   • 自动为每个Webhook生成示例URL
   • 使用{{ api_url }}模板变量确保URL正确

6. 恭喜完成宏 {!congrats.md!}

   • 插入成功设置集成的祝贺语
   • 通常放在文档末尾，示例截图之前

7. 事件过滤功能宏 {!event-filtering-additional-feature.md!}

   • 如果集成支持事件过滤，添加此部分
   • 列出可过滤的特定事件

文档编写最佳实践

总体原则

1. 简洁明了

   • 使用简单语言和命令式语气
   • 只描述必要内容
   • 避免冗余词语

2. 易于遵循

   • 按顺序描述操作步骤
   • 第三方UI元素使用粗体标注
   • 复杂的步骤可配截图

3. 易于维护

   • 尽量遵循现有文档的组织结构和措辞
   • 减少对截图的依赖

具体步骤指南

1. 开头描述

   • 以一句话简要说明集成功能
   • 示例："获取GitHub通知到Zulip！"

2. 创建频道步骤

   • 使用create-channel宏
   • 如果集成仅支持私信通知，可省略此步骤

3. 创建机器人步骤

   • 通常使用create-an-incoming-webhook和generate-integration-url宏
   • 这是所有集成文档的必需步骤

4. 导航步骤

   • 尽量合并为一个步骤
   • 示例："转到您的GitHub仓库"
   • 假设用户已登录账户

5. 表单填写步骤

   • 填写表单和保存操作合并为一个步骤
   • 复杂的表单可拆分

截图使用建议

1. 谨慎使用

   • 仅在第三方UI复杂或难以定位时使用
   • 避免包含整个网页

2. 截图规范

   • 尺寸要小
   • 只包含相关UI部分
   • 放在所描述的步骤之后

结语

编写高质量的集成文档对于提升Zulip用户体验至关重要。通过遵循上述指南，开发者可以创建清晰、一致且易于维护的集成文档，帮助用户轻松配置和使用各种集成功能。记住，好的文档应该像代码一样精心设计和维护。

zulip Zulip 服务器和Web应用程序。开源团队聊天工具，帮助团队保持生产力和专注度。 项目地址: https://gitcode.com/gh_mirrors/zu/zulip