Zendesk 所有面向公众的产品文档都发布在此 Zendesk 帮助中心。尽管 Zendesk 的大多数其他团队都直接在帮助中心创建内容,但 Docs 团队会在 DITA 源文件中离线创建和维护产品文档。DITA(即达尔文信息输入架构)是一个基于 XML 的数据模型,用于创作和发布内容。基本上,DITA 文件是纯文本 XML 文件。
本文章涵盖以下主题:
为什么选择 DITA?
DITA 是用于创建和维护大型文档集的行业标准。它旨在从单一来源以多个渠道发布内容。techwhirl.com 上的 Jacquie Samuels 对其尝试解决的问题进行了如下描述:
用 Word、电邮、PowerPoint、WordPress、HTML、InDesign、FrameMaker 或任何其它格式撰写内容,就如同在石板上书写一样。您的内容基本上被困在这种格式中,而且非常愚蠢。愚蠢的内容无法轻松重复使用或改变用途,效率低下且成本高昂。
DITA 是一种编写和存储内容的方式,使您可以像管理资产一样进行管理。它利用 XML(可扩展标记语言)使您的内容智能、通用、可管理且可移植。
例如,DITA 中的内容可以发布到(和完全品牌化的)PDF、HTML、RTF、PowerPoint 和移动设备,而无需在文件之间复制粘贴任何内容。
(来源:什么是 DITA?TechWhirl 上)
除了将内容与格式分离之外,DITA 对 Zendesk Docs 团队的其他好处如下:
- 迫使我们遵守内容结构。DITA 文件是 XML。如果结构无效,该工具将不允许我们对其进行任何操作。
- 使我们可以方便地移动内容。我们只需将主题节点从结构中的一个地方拖动到另一个地方。
- 允许我们通过在多篇文章中导入内容块来重复使用内容。
- 我们不经常发布 PDF,但会使用 DITA 源文件。
我们使用的 DITA 创作工具是 Oxygen XML Author。除了其强大的创作环境之外,我们还依赖于许多其他功能,包括搜索、验证和 XHTML 转换。其它 DITA 创作工具包括 Framemaker、Arbortext 和 XMetal(仅举几例)。
我们如何创作和发布文章
编写者使用 Oxygen XML Author 在 DITA 文件中创建或更新内容。由于创建 DITA 是为了允许从单一来源进行多渠道发布,因此 DITA 文本文件不包含样式。它们仅包含结构化内容。对于网络渠道,所有样式都由外部 CSS 样式表提供,而不是 DITA。在我们的例子中,所有的样式都由 Guide 主题中的样式表提供。
当我们准备好发布时(通常在发布或更新产品功能的同时),我们使用作者将 DITA 转换为 XHTML,这是一个更严格的 HTML 版本。然后我们使用 帮助中心 API将 XHTML 发布到帮助中心。
从版本 24 开始,Oxygen XML 编辑器 包括一个内置的转换场景,可以将 DITA 主题发布到 XHTML 输出,并将其作为文章直接上传到 Zendesk 帮助中心。请参阅 XML 编辑器中的 DITA 地图发布 帮助。如需视频,请参阅 XML 编辑器帮助中的 发布内容到 Zendesk 帮助中心 。
有时,我们需要在短时间内更新多篇文章。例如,当 Zendesk 简化其定价和品牌打造时,数百篇已修改的文章必须在上午 8 点之前发布特定日期的太平洋时间。在截止日期前的几周内,作者更新了 DITA 源文件,然后我们使用“作者”对文件进行了批量转换。我们使用帮助中心 API 将其推送到帮助中心。发布它们只需几分钟。
我们如何管理文件
我们使用 GitHub 来管理 DITA 文件。在创建或更新文章之前,作者会在我们的存储库中创建一个分支,进行更改,然后创建一个拉取请求。拉取请求由团队中的其他作者审阅。这样做的另一个好处是,作者有机会互相审阅彼此的工作。
我们将图像存储在 Amazon S3或 Amazon Simple Storage Service 中,这是一种由 Amazon Web Services (AWS) 提供的可扩展云存储服务。我们文章中的所有图像都从 S3 提供到您的浏览器,而不是来自帮助中心。Amazon S3 服务使图像管理更加简单。
我们如何发布本地化文章
我们帮助中心的默认语言是英语,我们还以德语、西班牙语、法语、日语、韩语、巴西葡萄牙语、意大利语和简体中文发布产品文档。
当本地化移交到期时,我们使用帮助中心 API 从帮助中心下载选定的英语文章,并将其写入 HTML 文件。我们使用 Amazon AWS API 从 Amazon S3 存储桶下载文章图像。我们将 HTML 文件和图像打包,交给本地化供应商。供应商返回翻译后,我们使用帮助中心 API 和 AWS API 上传文章和图像。
翻译免责声明:本文章使用自动翻译软件翻译,以便您了解基本内容。 我们已采取合理措施提供准确翻译,但不保证翻译准确性
如对翻译准确性有任何疑问,请以文章的英语版本为准。