技术写作基础概念：Docs as a product 与content first

目标读者：软体开发人员、DevOps 工程师、产品经理

概要

上一篇笔记提到Docs as Code，指的是以跟写程式一样或相似的工具与流程来制作文件。这篇笔记要再介绍两个有关技术文件写作的基础观念：

• Docs as a product ，指的是把「技术文件」当成一个产品来发展和维护。

• Content first ，即内容优先。既不是工具优先、平台优先，也不是美观样式优先。

Docs as a product

Documentation as a product 简称Docs as a product，指的是把「技术文件」当成一个产品来发展和维护。

乍听之下似乎很直观，没必要特别强调。但实际上，每个人写出来的技术文件不会完全一样，而文件对于目标读者是否「有用」才是最要紧的。并不是说，每个人今天搞懂了一项技术或know-how，键盘抄起来劈哩啪啦开始打字，便都可以立刻成就一篇易读易懂、对读者有用的文章。而且，如果本身肩负DevOps 相关工作，日常的程式开发、问题排查、技术支援等工作可能已占满大部分的时间（还有一堆会议？），恐怕也没有太多时间去思考一篇文章要怎样写才好。

能不能写出对读者有用的文章，除了需要掌握文章内容涉及的技术与know-how，更重要的是有没有去思考一篇文章该怎么写，才能让人读起来舒服、易懂、有学到东西或者解决他们手边碰到的问题。当然我们不能排除有的人已经是写手等级，或者对于想要写的内容早已在心中酝酿多时、胸有成竹，故可下笔如有神，一蹴而就。

简单来说，关键在于：身为作者的你，是否知道怎样的技术文件才是对多数的目标读者有帮助？如果写文件的过程能够经常考虑这点，并持续改善文件内容，我想已经走在对的道路上。能够做到这点，自然也就懂得docs as a product 是一个怎样的理念。

有关成为technical writer 的一些个人特质与要件，之后可能再另开一篇笔记来分享个人浅见。

总之，docs as a product 不是把技术文件当成零散笔记、随意为之，而是经过作者构思与细心整理的文件。作者知道知识传递与知识分享的重要性，他／她希望有更多人愿意读这些文件，且信任这些文件，故愿意投注长期的心力来持续改善文件的品质，就像持续改善一项产品那样。

Content first

内容优先，这也相当直观，文件首重其内容是否有用，自然是内容优先了。强调这点的原因是相对于其他考量来说的，例如：优先考虑文件撰写工具或文件管理平台是否容易取得、工具是否好用、产生出来的文件是否美观fancy 等等。

Content first 的前提是上一节介绍的docs as a product。因为有些文件并不需要那么严肃认真地对待，例如一些不稳定的知识、临时笔记、零碎知识等等，我们可能不会大费周章去把它们当成一个产品来发展与维护，于是内容结构如何、是否易读易懂，也就不需要那么讲究。

那么，如果要认真去写正规文件，该如何构思文件的架构呢？

构思文件架构

一旦确定要撰写正规文件，把文件当成一项产品来认真看待，便需要规划和构思文件结构与内容。此时，有一个名为Diátaxis的文件构思框架可以派上用场。如下图（取自diataxis.fr ）：

此框架把文件分成四大类：

• 教学文件：协助读者学习某一个主题。

• How-to 文件：包含完成特定工作或目标的指引。例如「如何建立虚拟机器」、「手把手教你XYZ」通常属于此类。

• 解释型文件：说明某个概念、名词、架构等等都是。

• 参考文件：提供参考资讯，例如error codes、API reference manual 等等。

构思技术文件该包含哪些内容时，不妨以此框架来规划文件的架构。

有了大分类之后，可以再进一步思考更细、更具体的文件类型，例如：

• Introduction、overview

• Tutorials

• Use cases and best practices

• FAQs

• API reference manual

• 专有名词（terminology）

• 产品的road map

• 产品的release notes

• 联系技术支援的管道

• 提供有关文件内容feedback 的管道

• 相关法规与政策

规划文件内容架构时，若想不到该放哪些东西到文件中，不妨利用上述清单来刺激灵感。

结语

本文提及的概念和方法，都是我赞同且正在使用的，而且我觉得对于从事软体开发或系统工程方面的DevOps 与工程师特别合适，因为相对容易上手。比如说，让DevOps team 成员学习使用markdown 来写文件，碰到的抗拒通常会比一般习惯用Word 和Powerpoint 写文件的人来得低。

然而，也不能预设只有DevOps 工程师才能使用这套方法来写文件。理想情况下，撰写文件的相关配套工具、平台、教学文件，也都应该尽量准备齐全而且容易上手，让组织中的其他角色（例如PM、SA）也能参与文件协作、贡献知识。

最后，最重要的，无论采用何种工具，只要是正规文件，都应该以易读易懂为目标，而且能让读者自行阅读文件就学会特定知识、或解决特定问题（而不是看了文件感觉一头雾水还得一直去找人问）。

喔对了，非正规文件当然也可以用上述理念和方法来撰写，例如部落格就是练习写文件的一个好方法（尽管有点老派，但还是很棒的方法）。

Keep writing!

延伸阅读

• Docs as Code 与知识管理系统

• Diátaxis 文件类型框架

• Crafting Docs for Success: An End-to-End Approach to Developer Documentation by Diana Lakatos

• I'd Rather Be Writing

本文转贴自Huanlin's Note