Doc as Code (3)：业内人士的观点

news2024/11/15 21:58:33

作者 | Anne-Sophie Lardet

在技术传播国际会议十周年之际，Fluid Topics 的认证技术传播者和功能顾问 Gaspard上台探讨了“docOps 作为实现Doc as Code的中间结构”的概念。在他的演讲中，观众提出了几个问题，我们想分享Gaspard的见解！

首先，让我们从Doc as Code的介绍开始。

- 1 -

什么是Doc as Code

Doc as Code是应用软件开发流程和工具来交付技术文档。它使用与开发团队相同的工作流程和工具，包括版本控制系统、自动化测试、问题跟踪器等。它还依赖于轻量级文件的生产和管理。

Doc as Code相当容易获得且易于使用。需要的工具是极简的，通常是免费的，并且像文本编辑器一样简单。Markdown 或 AsciiDoc 等轻量级格式是开始使用Doc as Code的最快方法，因为它们都可以处理纯文本文件。

与任何技术范例一样，Doc as Code有其优点和缺点。

优点

它促进TW和开发人员之间的合作
您可以使用与开发人员相同的工具
它让开发人员一起参与文档生产制作
它降低了软件许可和支持服务的总体成本

缺点

需要更深的技术知识
最适合软件产品的文档

许多机构和公司已转向Doc as Code作为他们的文档流程。英国政府的技术文档团队使用Doc as Code来提供服务和平台。Spotify、Cloudfare、Kubernetes、Twitch、Arundo、Netflix设备，甚至Bitcoin等公司都使用静态站点生成器（SSG）Jekyll，这是Doc as Code场景最常见的发布工具之一。

- 2 -

与DITA可能存在哪些交互?

Doc as Code和DITA的基本原理是不同的，但两者可以共存。

2019年6月，Heretto联合创始人兼首席执行官Patrick Bosek发表了《和睦相处：DITA和Markdown》。他做了如下类比：

Markdown就像一把铲子，DITA就像一台挖土机。有些人从未使用过挖土机，认为它太复杂了。然后，建造大型建筑的建筑工人说：你不能用铲子建造大型建筑。

如果你一个人开始一个项目，却不知道如何操作挖土机，那么铲子似乎是显而易见的选择。他们俩在世界上都有一席之地，任何建筑工地都会有铲子和挖土机。

Bosek强调了这样一个事实，即每个文档标准都有其优势，我们应该利用每一个标准的长处。

DITA和Doc as Code常用的格式之间存在潜在的联系。

轻量级DITA

您可以使用轻量级DITA来弥合结构化内容和连续文档之间的差距，轻量级DITA是DITA的简化版本，使用DITA元素类型、属性、内容模型的子集和简化的功能子集。轻量级DITA旨在结合HTML5（HDITA）和Markdown（MDITA），它不是为了取代DITA。它主要针对那些将不懂DITA的员工融入文档组织。它允许作者跨不同的部门来进行编辑、协作或发布。

DITA辅助编辑模式

当有良好用户体验的界面提供支持时（即：有好用的编辑器），利用 XML 的好处可能是有意义的。随着文档化自动化技术向最终用户友好界面发展，开发人员可能需要访问专门的编辑和管理环境。有一些解决方案可以帮助生成一致的DITA，如Oxygen XML、IXIASOFT、Heretto、DitaToo、Composize等。

- 3 -

可以添加元数据吗？

有些内容需要比其他内容有更多的语义。在DITA系统中，有不同的方法可以在Topic或Map级别声明和添加元数据。不幸的是，使用Markdown，虽然可以调整现有内容并添加元数据，但没有像DITA那样提供语义化。以下是一些如何做到这一点的提示：

使用YAML文件将元数据与模板语言相结合
利用Markdown文件的header或为每个相关目录创建一个README文件
使用Markdown特定风格，如Kramdown，它向内联元素添加类和ID
将带有class属性的HTML标签与Markdown内容结合起来
利用类似AsciiDocsy的SSG，它使用内联语义。

例如：.term, .cite, .cmd, .code, .gui, .path, .case和.tip

- 4 -

是否仅限于软件行业？

Doc as Code确实适合很多公司，但通常仍与软件开发有关。

重工业在编制技术文件时使用有约束力的规范，如航空、航天、海军、核能和铁路的S1000D标准。有一些特定的要求和时间表与软件行业不同，因此Doc as Code很难应用。

另一方面，Doc as Code作为一个全球的环境可能适用于不同的内容来源、知识库、教育内容，甚至依赖聊天机器人的技术。

- 5 -

给初次尝试团队的建议

循序渐进，从试点开始，熟悉版本控制系统和协作工作流
提升TW的GIT技能
促进技术文档团队和开发人员之间的沟通，让他们参与到文档流程中，并帮助他们确定工作的优先级
花点时间选择和评估用于发布的现有解决方案（如静态站点生成器）是否符合您的需求
为每个存储库创建一个README文件，以了解项目范围、所需资源、原则和指南
开发模板，实施样式指南，代码检查，并考虑将其集成到CI/CD管道中
比较Markdown的不同风格，并考虑使用AsciiDoc甚至轻量级DITA进行创作
随时了解专业社区共享的文章、研讨会和资源：
- Write the docs：
  
  https://www.writethedocs.org/
- Tom Johnson：
  
  https://idratherbewriting.com/
- Anne Gentle：
  
  https://justwriteclick.com/
- Brian Dominick：
  
  https://github.com/briandominick