将文档写作加入到 DevOps 的生命周期中。

DevOps 正在挑战技术文档的规范，这在 IT 历史上是前所未有的。从自动化到提高交付速度，再到拆除瀑布式软件开发生命周期模型，这意味着业务和技术文档写作的理念需要做出巨大改变。

以下是 DevOps 对技术文档写作不同方面的影响。

技术写手的角色变化

技术写手必须适应 DevOps。好消息是，许多技术写手已经加入到开发团队中，并且拥有合作关系和不断增长的产品知识的技术写手很具优势。

但是如果一个技术写手习惯于独立工作，并依赖于领域专家的草稿作为文档的基础，那么就需要做一些调整。

进行一些投资，以确保文档和其他与项目有关的内容开发工作获得所需的工具、结构和支持。从改变 技术写手聘用方式 开始。以 DevOps 的速度 编写文档需要重新思考内容规划，并打破 DevOps 团队和支持项目的技术写手之间长期存在的隔阂。

DevOps 使开发团队摆脱了传统文档实践的束缚。首先，文档 完成的定义 必须改变。一些企业的文化使技术写手成为软件开发的被动参与者。DevOps 提出了新的要求：随着 DevOps 文化的转变，技术写手的角色也应发生变化。技术写手需要（且必须适应）DevOps 提供的透明度。他们必须融入 DevOps 团队。取决于组织如何塑造这个角色，将技术写手带入团队可能会带来技能上的挑战。

文档标准、方法和规格

虽然 DevOps 还没有影响到技术文档本身，但开源社区已经加强了对应用编程接口（API）文档的帮助，已经有不同规模的企业的 DevOps 团队正在使用这些文档。

用于记录 API 的开源规范和工具是个非常值得关注的领域。我想这是由于 谷歌文档季 的影响，它使开源软件项目能够获得专业的技术写作人才来解决他们最关键的文档项目。

开源 API 属于 DevOps 文档讨论的一部分。云原生应用集成需求的重要性正在上升。OpenAPI 规范（一个定义和记录 API 的开放标准）是在 DevOps 环境下 API 文档的良好资源。然而，该规范会导致文档的创建和更新过程变得很费时，这使其饱受批评。

曾经也有短暂尝试过创建 持续文档 Continuous Documentation ，并且还有一个来自 CA（现在的 Broadcom）的创建 DocOps 框架的运动。然而，DocOps 从来没有作为一个行业运动流行起来。

DevOps 文档标准的现状意味着 DevOps 团队（包括技术写手）需要在项目的最初阶段就开始创建文档。要做到这一点，你需要把文档作为一个敏捷故事和（同样重要的）管理期望，并且把它与年度绩效评估放在一起执行。

文档工具

文档的编写应该以一种所有团队成员都可以使用的格式或平台在线进行。MediaWiki、DokuWiki、TikiWiki 和其他 开源维基 为 DevOps 团队提供了一个编写和维护文档的中央仓库。

让团队选择他们的维基平台，就像让他们选择他们的其他持续集成/持续开发（CI/CD）工具链一样。开源维基强大之处在于其可扩展性。例如，DokuWiki 包括一系列的扩展，你可以通过安装这些扩展来创建一个符合你的 DevOps 团队的创作要求的平台。

如果你有足够的野心来加强你的团队的编写和协作能力，Nextcloud（一个开源的云协作套件）是一个让你的 DevOps 团队上网并给他们提供编写文档所需工具的选择。

DevOps 最佳实践

文档在 DevOps 转型中也发挥着作用。例如，你会想要记录组织从 DevOps 实现效率和流程增益的最佳实践，这些信息太重要了，不能靠着 DevOps 团中之间口耳相传。如果你所在的组织有多个 DevOps 团队，那么文档就是统一的力量，它可以促进最佳实践的标准化，并设置了衡量代码质量的基准指标。

一般情况下，开发人员承担了记录 DevOps 实践的工作。即使他们的组织有技术写手，他们也可能跨开发团队工作。因此，开发人员和系统管理员能够捕捉、记录和交流他们的最佳实践是很重要的。这里有一些朝正确的方向发展的提示：

• 提前花时间为 DevOps 最佳实践创建标准模板。不要陷入复制在线模板的陷阱。采访利益相关者和团队来创建一个符合团队需求的模板。
• 寻找一些创造性的信息收集的方法，例如记录团队会议和使用聊天系统日志来作为文档的基础。
• 建立一个用于发布最佳实践的维基。使用维基可以跟踪编辑和更新。这样的平台可以帮助团队在最佳实践发生变化时进行更新和维护。

当在构建 CI/CD 工具链时记录依赖关系是非常明智的。尤其是当加入新的团队成员时，你会发现这些记录非常有用，另外当团队成员忘记一些事情时，这也是一种保险。

最后，自动化对 DevOps 利益相关者和从业者都很有吸引力。在自动化中断之前，一切都很有趣。拥有自动化运行手册、管理指南和其他内容的文档（并且是最新的）意味着无论何时发生故障，员工都可以让自动化重新工作。

最后一些想法

DevOps 对于技术文档来说是一个积极的因素。它将内容开发纳入 DevOps 生命周期，并打破组织文化中开发人员和技术作者之间的隔阂。在没有技术写手的情况下，团队就可以使用工具来加快文档创作的速度，以与 DevOps 的速度相匹配。

你的组织将如何把文档加入到 DevOps 生命周期？请在评论区分享你的经验。

via: https://opensource.com/article/21/3/devops-documentation

作者：Will Kelly 选题：lujun9972 译者：Veryzzj 校对：校对者ID

本文由 LCTT 原创编译，Linux中国 荣誉推出

有些项目长期保持活跃，有些项目却过早消亡 —— 这两者的区别往往在于它们的文档。严谨、聪明的文档可以给你的项目带来它所需要的动力。你应该把文档工作视为一项主要工作，把它与开发相提并论，下面我将说明这么做的理由和正确的做法。

经常会有开发者简单地认为他们的代码的“ 自我描述 self-documented ”已经足够了，继而认为额外的文档是没有必要的。这种过度的自信会让项目付出很大的代价。匮乏或差劲的文档会扼杀你的项目。没有适当的文档，用户将无法理解项目的目标以及正确的工作流程。这可能会导致人们对采用你的开源产品产生一些疑虑。

撰写文档，从项目第一天就开始

文档不应该是次要的工作，它应该是与代码开发和管理同等的主要任务。随着内容以 Community Threads、Stack Overflow 和 Quora 问答等形式的广泛传播，文档承担了“ 信息源 source of truth ”的角色。它应该满足那些想参考一手资料的贡献者的需要，并给工程师提供必要的参考支持。它还应该与利益相关者沟通基本计划。一个好的文档可以确保产品的持续改进和发展。

当发布一个软件产品时，我们不仅要发布代码，还要发布好的文档。这给我们带来了一个最重要的概念，大多数良好维护了文档的开源项目都遵循这个概念 —— “ 文档即代码 Documentation as code ”。

文档及代码

今天，文档不再被存储为微软 Word 或 PDF 文件。新的需求是版本控制文档，其中所有的文档都是通过版本控制系统添加的，并持续发布。这个概念因 Read the Docs（LCTT 译注：一个文档创建、托管和浏览的平台）而流行，现在已经成为大多数文档团队的内容策略的重要组成部分。

像 Bugzilla 和 GitHub 议题 Issue 这样的工具可以用来跟踪待处理的文档工作，并从维护者和用户那里获得反馈以验证文档的发布。外部审查可以用来验证文档作品，并持续发布文档。这就保证了除代码外，文档也能不断改进并快速发布。

请记住，如果不遵循规范化的实践，每个文档都会不同。这可能会导致一些混乱，使人们难以获取正确的信息。

哪些东西会被归类为混乱呢？当大多数文件都不遵循规范实践时，不一致就会产生，从而导致更大的混乱！那么，如何整理混乱的开源文档呢？

整理混乱的开源文档

遵循一个“文档风格指南”是很重要的。风格指南是创建和展示内容的指导方针的集合。无论你是一个独立的作家还是一个大型文档团队的成员，它都有助于在你的文档中保持一致的风格、口音和语气。

有几个流行的风格指南，如《红帽风格指南》、《谷歌文档风格指南》和《苹果风格指南》。如何选用？首先要从定义你的需求开始。如果你的要求与其他开源项目没有太大区别，你可以遵循一个现成的风格指南，或者你也可以先选一个，然后在它的基础上根据自身需要做一些修改。大多数与语法有关的准则和内容规则可能是通用的，但整体术语可能会有所不同。

你还需要在你的项目中自动采用这些风格指南。为此，你可以使用 Vale，它集成了本地的持续集成（CI）服务，该服务能帮助你确保文档严格遵循风格指南。

文档类型

• 自述文件：包含基本的安装和使用说明，这也是任何开源文档中最重要的部分之一。它是潜在的用户/开发者与项目之间的第一个连接点。
• 参考指南：可能包括一些基本的参考资料，以便帮助你快速上手，或者是与项目贡献相关的文档。
• 用户文档：是最基本的文档，它描述了项目的使用方式。如果没有用户文档，大多数人就会对如何使用该项目感到迷茫。
• 开发文档：旨在支持开发团队在项目中不断取得新的进展。它还应该为内部开发工作提供一个良好的途径，并确保功能被很好地传达给股东。
• 社区内容：包括基本的博客、视频和外部内容，旨在为那些想进一步了解项目的社区成员提供支持。

通过使用风格指南，文件的整体前提将以统一的语言风格传达给用户。但是，这些文件毕竟是由一个技术作家团队准备的，它们的写作风格可能会冲突，因为写作风格是因人而异的。那么，如何才能使文档规范化呢？

规范化文档

当涉及到规范化文档时，有许多方法可以采取。第一个方法显然是创建适用于各种角色的预定义模板。这些模板可以用来记录新的功能、识别错误和问题，以及更新变更日志以适应正在增加的新内容。

如果你采用的是基于 Git 的工作流，试着开发一个规范的工作流程来发布你的文档。最规范的工作流是： 复刻 fork 发布文档的仓库，在本地分支上添加你的修改，推送这些修改，提出请求并要求对其进行审查。规范化文档的一个好处就是带来更好的反馈和审查过程。

反馈和自动审查

规范化使得你能够得到用户的反馈并生成自动的审查，可以参考这些反馈来改进项目和文档。通过这些反馈，你也可以评估所分享的信息对用户是否有意义。像 GitBook 这样的文档平台会提供合适的反馈服务，这有助于验证文档是否有用。

始终寻求 主题专家 subject matter expert （SME）对文档的反馈，他们可以是利益相关者、开发者、工程师，甚至是外部贡献者。你也可以使用自动测试和 CI 来验证你的文档是否遵循风格指南。

文档众包

如果你想开源你的文档，最好的方法也许是提供一个快速入门指南。它可以像 CONTRIBUTING.md 那样简单，基本上只要说明该如何设置项目并为其作出贡献/单纯使用它即可。

始终开发以用户为中心的文档，标明每个项目的目的。同时，打造学习课程来帮助新的贡献者。

带着目的编写文档

始终带着目的编写文档。它是最基本的写作策略之一，它定义了你编写某个特定文档的理由，而非方式。首先回答以下问题：

• 这个文档的目标是什么？
• 需要传递的信息是什么？
• 你希望用户在这之后采取什么行动？
• 我与读者分享的价值观是什么？
• 我的文档风格是否简洁、一致？

定义一致的内容策略

一致的内容策略有助于确保文档工作和项目基础设施的长期愿景。它可以围绕以下两个主要方面：

1. 资源：包括项目文档、案例研究和白皮书、项目架构等
2. 品牌内容：博客和特邀帖子、新闻和社区故事、学习课程等

每个开源项目都应该有适当的文档，以说明它能为用户提供的功能，这样用户就可以选择最合适的解决方案。适当的文档可以传达正确的信息，也可以让其他开发者贡献力量来进一步加强和改进项目。虽然听起来很简单，但只有做对了，文档才能成功。而你的项目，反过来，只有在你的文档正确的情况下才能成功，所以永远不要低估它的目标或过程！

策划：Laveesh Kocher

via: https://www.opensourceforu.com/2022/04/documentation-isnt-just-another-aspect-of-open-source-development/

作者：Harsh Bardhan Mishra 选题：lkxed 译者：lkxed 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

使用有效沟通的一些基本原则可以帮助你创建与你的品牌一致的、编写良好、内容丰富的项目文档。

在开始实际撰写又一个开源项目的文档之前，甚至在采访专家之前，最好回答一些有关新文档的高级问题。

著名的传播理论家 Harold Lasswell 在他 1948 年的文章《 社会中的传播结构和功能 The Structure and Function of Communication in Society 》中写道：

（一种）描述沟通行为的方便方法是回答以下问题：

• 谁
• 说什么
• 在哪个渠道
• 对谁
• 有什么效果？

作为一名技术交流者，你可以运用 Lasswell 的理论，回答关于你文档的类似问题，以更好地传达你的信息，达到预期的效果。

谁：谁是文档的所有者？

或者说，文档背后是什么公司？它想向受众传达什么品牌形象？这个问题的答案将极大地影响你的写作风格。公司可能有自己的风格指南，或者至少有正式的使命声明，在这种情况下，你应该从这开始。

如果公司刚刚起步，你可以向文件的主人提出上述问题。作为作者，将你为公司创造的声音和角色与你自己的世界观和信念结合起来是很重要的。这将使你的写作看起来更自然，而不像公司的行话。

说什么：文件类型是什么？

你需要传达什么信息？它是什么类型的文档：用户指南、API 参考、发布说明等？许多文档类型有模板或普遍认可的结构，这些结构为你提供一个开始的地方，并帮助确保包括所有必要的信息。

在哪个渠道：文档的格式是什么？

对于技术文档，沟通的渠道通常会告诉你文档的最终格式，也就是 PDF、HTML、文本文件等。这很可能也决定了你应该使用什么工具来编写你的文档。

对谁：目标受众是谁？

谁会阅读这份文档？他们的知识水平如何？他们的工作职责和主要挑战是什么？这些问题将帮助你确定你应该覆盖什么内容，是否应该应该涉及细节，是否可以使用特定的术语，等等。在某些情况下，这些问题的答案甚至可以影响你使用的语法的复杂性。

有什么效果：文档的目的是什么？

在这里，你应该定义这个文档要为它的潜在读者解决什么问题，或者它应该为他们回答什么问题。例如，你的文档的目的可以是教你的客户如何使用你的产品。

这时，你可以参考 Divio 建议的方法。根据这种方法，你可以根据文档的总体方向，将任何文档分为四种类型之一：学习、解决问题、理解或获取信息。

在这个阶段，另一个很好的问题是，这个文档要解决什么业务问题（例如，如何削减支持成本）。带着业务问题，你可能会看到你写作的一个重要角度。

总结

上面的问题旨在帮助你形成有效沟通的基础，并确保你的文件涵盖了所有应该涵盖的内容。你可以把它们分解成你自己的问题清单，并把它们放在身边，以便在你有文件要创建的时候使用。当你面对空白页无从着笔时，这份清单也可能会派上用场。希望它能激发你的灵感，帮助你产生想法。

via: https://opensource.com/article/20/9/project-documentation

作者：Alexei Leontief 选题：lujun9972 译者：geekpi 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

使用 Docsify 创建文档网页并发布到 GitHub Pages 上。

文档是帮助用户使用开源项目一个重要部分，但它并不总是开发人员的首要任务，因为他们可能更关注的是使他们的应用程序更好，而不是帮助人们使用它。对开发者来说，这就是为什么让发布文档变得更容易是如此有价值的原因。在本教程中，我将向你展示一个这样做的方式：将 Docsify 文档生成器与 GitHub Pages 结合起来。

默认情况下，GitHub Pages 会提示用户使用 Jekyll，这是一个支持 HTML、CSS 和其它网页技术的静态网站生成器。Jekyll 可以从以 Markdown 格式编码的文档文件中生成一个静态网站，GitHub 会自动识别它们的 .md 或 .markdown 扩展名。虽然这种设置很好，但我想尝试一下其他的东西。

幸运的是，GitHub Pages 支持 HTML 文件，这意味着你可以使用其他网站生成工具（比如 Docsify）在这个平台上创建一个网站。Docsify 是一个采用 MIT 许可证的开源项目，其具有可以让你在 GitHub Pages 上轻松创建一个有吸引力的、先进的文档网站的功能。

开始使用 Docsify

安装 Docsify 有两种方法：

1. 通过 NPM 安装 Docsify 的命令行界面（CLI）。
2. 手动编写自己的 index.html。

Docsify 推荐使用 NPM 方式，但我将使用第二种方案。如果你想使用 NPM，请按照快速入门指南中的说明进行操作。

从 GitHub 下载示例内容

我已经在该项目的 GitHub 页面上发布了这个例子的源代码。你可以单独下载这些文件，也可以通过以下方式克隆这个存储库。

git clone https://github.com/bryantson/OpensourceDotComDemos

然后 cd 进入 DocsifyDemo 目录。

我将在下面为你介绍这些代码，它们克隆自我的示例存储库中，这样你就可以理解如何修改 Docsify。如果你愿意，你也可以从头开始创建一个新的 index.html 文件，就像 Docsify 文档中的的示例一样：

<!-- index.html -->

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

探索 Docsify 如何工作

如果你克隆了我的 GitHub 存储库，并切换到 DocsifyDemo 目录下，你应该看到这样的文件结构：

index.html 是 Docsify 可以工作的唯一要求。打开该文件，你可以查看其内容：

<!-- index.html -->

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
  <title>Docsify Demo</title>
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      el: "#app",
      repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo',
      loadSidebar: true,
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

这本质上只是一个普通的 HTML 文件，但看看这两行：

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
... 一些其它内容 ...
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

这些行使用内容交付网络（CDN）的 URL 来提供 CSS 和 JavaScript 脚本，以将网站转化为 Docsify 网站。只要你包含这些行，你就可以把你的普通 GitHub 页面变成 Docsify 页面。

<body> 标签后的第一行指定了要渲染的内容：

<div id="app"></div>

Docsify 使用单页应用（SPA）的方式来渲染请求的页面，而不是刷新一个全新的页面。

最后，看看 <script> 块里面的行：

<script>
    window.$docsify = {
      el: "#app",
      repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo',
      loadSidebar: true,
    }
</script>

在这个块中：

• el 属性基本上是说：“嘿，这就是我要找的 id，所以找到它并在那里呈现。”
• 改变 repo 值，以确定当用户点击右上角的 GitHub 图标时，会被重定向到哪个页面。
• 将 loadSideBar 设置为 true 将使 Docsify 查找包含导航链接的 _sidebar.md 文件。

你可以在 Docsify 文档的配置部分找到所有选项。

接下来，看看 _sidebar.md 文件。因为你在 index.html 中设置了 loadSidebar 属性值为 true，所以 Docsify 会查找 _sidebar.md 文件，并根据其内容生成导航文件。示例存储库中的 _sidebar.md 内容是：

<!-- docs/_sidebar.md -->


* [HOME](./)

* [Tutorials](./tutorials/index)
  * [Tomcat](./tutorials/tomcat/index)
  * [Cloud](./tutorials/cloud/index)
  * [Java](./tutorials/java/index)

* [About](./about/index)

* [Contact](./contact/index)

这会使用 Markdown 的链接格式来创建导航。请注意 “Tomcat”、“Cloud” 和 “Java” 等链接是缩进的；这意味着它们被渲染为父链接下的子链接。

像 README.md 和 images 这样的文件与存储库的结构有关，但所有其它 Markdown 文件都与你的 Docsify 网页有关。

根据你的需求，随意修改你下载的文件。下一步，你将把这些文件添加到你的 GitHub 存储库中，启用 GitHub Pages，并完成项目。

启用 GitHub 页面

创建一个示例的 GitHub 存储库，然后使用以下 GitHub 命令检出、提交和推送你的代码：

$ git clone 你的 GitHub 存储库位置
$ cd 你的 GitHub 存储库位置
$ git add .
$ git commit -m "My first Docsify!"
$ git push

设置你的 GitHub Pages 页面。在你的新 GitHub 存储库中，点击 “Settings”：

向下滚动直到看到 “GitHub Pages”：

查找 “Source” 部分：

点击 “Source” 下的下拉菜单。通常，你会将其设置为 “master branch”，但如果你愿意，也可以使用其他分支：

就是这样！你现在应该有一个链接到你的 GitHub Pages 的页面了。点击该链接将带你到那里，然后用 Docsify 渲染：

它应该像这样：

结论

通过编辑一个 HTML 文件和一些 Markdown 文本，你可以用 Docsify 创建一个外观精美的文档网站。你觉得怎么样？请留言，也可以分享其他可以和 GitHub Pages 一起使用的开源工具。

via: https://opensource.com/article/20/7/docsify-github-pages

作者：Bryant Son 选题：lujun9972 译者：wxy 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

一份优质的文档可以让很多用户对你的项目路人转粉。

好的代码很多时候并不代表一切。或许你能用最精巧的代码解决了世界上最迫切需要解决的问题，但如果你作为一个开源开发者，没能用准确的语言将你的作品公之于世，你的代码也只能成为沧海遗珠。因此，技术写作和文档编写是很重要的技能。

一般来说，项目中的文档是最受人关注的部分，很多用户会通过文档来决定自己是否应该对某个项目开始学习或研究。所以，我们不能忽视技术写作和文档编写的工作，尤其要重点关注其中的“ 入门 Getting Started ”部分，这会对你项目的发展起到关键性的作用。

对于很多人来说，写作是一件令人厌烦甚至恐惧的事情。我们这些工程师出身的人，更多学习的是“写代码”而不是学习“为代码写文档”。不少人会把英语作为自己的第二语言或者第三语言，他们可能会对英语写作感到不自信甚至害怕（我的母语是汉语，英语是作为我的第二语言学习的，所以我也能感受到这种痛苦）。

但如果你希望自己的项目能在全球范围内产生一定的影响力，英语就是你必须使用的语言，这是一个无法避免的现实。但不必害怕，我在写这篇文章的时候就考虑到了这些可能带来的挑战，并给出了我的一些建议。

五条有用的写作建议

这五条建议你马上就可以用起来，尽管看起来似乎有些浅显，但在技术写作时却经常被忽视。

1. 使用主动语态：感受一下主动语态下的“你可以这样更改配置（You can change these configurations by…）”和被动语态下的“配置可以这样更改（These configurations can be changed by…）”有什么不同之处。
2. 使用简洁明了的句子：可以借助 Hemingway App 或者 Grammarly 这样的工具，尽管它们并不开源。
3. 保持条理性：你可以在文档中通过写标题、划重点、引链接等方式，把各类信息划分为不同的部分，避免将所有内容都杂糅在一大段冗长的文字当中。
4. 提高可读性：除了单纯的文字之外，运用图表也是从多种角度表达的手段之一。
5. 注意拼写和语法：必须记得检查文档中是否有拼写错误或者语法错误。

只要在文档的写作和编辑过程中应用到这些技巧，你就能够和读者建立起沟通和信任。

• 高效沟通：对于工程师们来说，阅读长篇大论的冗长文字，还不如去看小说。在阅读技术文档时，他们总是希望能够从中快速准确地获取到有用的信息。因此，技术文档的最佳风格应该是精简而有效的，不过这并不代表文档中不能出现类似幽默、emoji 甚至段子这些东西，这些元素可以当你的文档更有个性、更使人印象深刻。当然，具体的实现方式就因人而异了
• 建立信任：你需要取得文档读者们的信任，这在一个项目的前期尤为重要。读者对你的信任除了来源于你代码的质量，还跟你文档编写的质量有关。所以你不仅要打磨代码，还要润色好相关的文档，这也是上面第 5 点建议拼写和语法检查的原因。

从编写“入门”文档开始

现在，最需要花费功夫的应该就是“入门”部分了，这是一篇技术文档最重要的部分，二八定律在这里得到了充分体现：访问一个项目的大部分流量都会落在项目文档上，而访问项目文档的大部分流量则会落在文档的“入门”部分中。因此，如果文档的“入门”部分写得足够好，项目就会吸引到很多用户，反之，用户会对你的项目敬而远之。

那么如何写好“入门”部分呢？我建议按照以下三步走：

1. 任务化：入门指南应该以任务为导向。这里的任务指的是对于开发者来说可以完成的离散的小项目，而不应该包含太多涉及到体系结构、核心概念等的抽象信息，因此在“入门”部分只需要提供一个简单明了的概述就可以了。也不要在“入门”部分大谈这个项目如何优秀地解决了问题，这个话题可以放在文档中别的部分进行说明。总而言之，“入门”部分最好是给出一些主要的操作步骤，这样显得开门见山。
2. 30 分钟内能够完成：这一点的核心是耗时尽可能短，不宜超过 30 分钟，这个时间上限是考虑到用户可能对你的项目并不了解。这一点很重要，大部分愿意浏览文档的人都是有技术基础的，但对你的项目也仅仅是一知半解。首先让这些读者尝试进行一些相关操作，在收到一定效果后，他们才会愿意花更多时间深入研究整个项目。因此，你可以从耗时这个角度来评估你的文档“入门”部分有没有需要改进之处。
3. 有意义的任务：这里“有意义”的含义取决于你的开源项目。最重要的是认真思考并将“入门”部分严格定义为一项任务，然后交给你的读者去完成。这个项目的价值应该在这项有意义的任务中有所体现，不然读者可能会感觉这是一个浪费时间的行为。

提示：假如你的项目是一个分布式数据库，那么达到“整个集群在某些节点故障的情况下可以不中断地保持可用”的目标就可以认为是“有意义”的；假如你的项目是一个数据分析工具或者是商业智能工具，“有意义”的目标也可以是“加载数据后能快速生成多种可视化效果的仪表板”。总之，无论你的项目需要达到什么“有意义”的目标，都应该能在笔记本电脑上本地快速实现。

Linkerd 入门就是一个很好的例子。Linkerd 是一个开源的 Kubernetes 服务网格 Service Mesh ，当时我对 Kubernetes 了解并不多，也不熟悉服务网格。但我在自己的笔记本电脑上很轻松地就完成了其中的任务，同时也加深了对服务网格的理解。

上面提到的三步过程是一个很有用的框架，对一篇文档“入门”部分的设计和量化评估很有帮助。今后你如果想将你的开源项目产品化，这个框架还可能对 实现价值的时间 time-to-value 产生影响。

其它核心部分

认真写好“入门”部分之后，你的文档中还需要有这五个部分：架构设计、生产环境使用指导、使用案例、参考资料以及未来展望，这五个部分在一份完整的文档中是必不可少的。

• 架构设计：这一部分需要深入探讨整个项目架构设计的依据，“入门”部分中那些一笔带过的关键细节就应该在这里体现。在产品化过程中，这个部分将会是产品推广计划的核心，因此通常会包含一些可视化呈现的内容，期望的效果是让更多用户长期参与到项目中来。
• 生产环境使用指导：对于同一个项目，在生产环境中部署比在笔记本电脑上部署要复杂得多。因此，指导用户认真使用就尤为重要。同时，有些用户可能对项目很感兴趣，但对生产环境下的使用有所顾虑，而指导和展示的过程则正好能够吸引到这类潜在的用户。
• 使用案例： 社会认同 social proof 的力量是有目共睹的，所以很有必要列出正在生产环境使用这个项目的其他用户，并把这些信息摆放在显眼的位置。这个部分的浏览量甚至仅次于“入门”部分。
• 参考资料：这个部分是对项目的一些详细说明，让用户得以进行详细的研究以及查阅相关信息。一些开源作者会在这个部分事无巨细地列出项目中的每一个细节和 边缘情况 edge case ，这种做法可以理解，但不推荐在项目初期就在这个部分花费过多的时间。你可以采取更折中的方式，在质量和效率之间取得平衡，例如提供一些相关社区的链接、Stack Overflow 上的标签或单独的 FAQ 页面。
• 未来展望：你需要制定一个简略的时间表，规划这个项目的未来发展方向，这会让用户长期保持兴趣。尽管项目在当下可能并不完美，但要让用户知道你仍然有完善这个项目的计划。这个部分也能让整个社区构建一个强大的生态，因此还要向用户提供表达他们对未来展望的看法的交流区。

以上这几个部分或许还没有在你的文档中出现，甚至可能会在后期才能出现，尤其是“使用案例”部分。尽管如此，还是应该在文档中逐渐加入这些部分。如果用户对“入门”部分已经感觉良好，那以上这几个部分将会提起用户更大的兴趣。

最后，请在“入门”部分、README 文件或其它显眼的位置注明整个项目所使用的许可证。这个细节会让你的项目更容易通过最终用户的审核。

花 20% 的时间写作

一般情况下，我建议把整个项目 10% 到 20% 的时间用在文档写作上。也就是说，如果你是全职进行某一个项目的，文档写作需要在其中占半天到一天。

再细致一点，应该将写作纳入到常规的工作流程中，这样它就不再是一件孤立的琐事，而是日常的事务。文档写作应该随着工作进度同步进行，切忌将所有写作任务都堆积起来最后完成，这样才可以帮助你的项目达到最终目标：吸引用户、获得信任。

特别鸣谢云原生计算基金会的布道师 Luc Perkins 给出的宝贵意见。

本文首发于 COSS Media 并经许可发布。

via: https://opensource.com/article/20/3/documentation

作者：Kevin Xu 选题：lujun9972 译者：HankChow 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

最好将文档作为开发过程的一部分。Sphinx 加上 Tox，让文档可以轻松书写，并且外观漂亮。

Python 代码可以在源码中包含文档。这种方式默认依靠 docstring，它以三引号格式定义。虽然文档的价值是很大的，但是没有充足的文档的代码还是很常见。让我们演练一个场景，了解出色的文档的强大功能。

经历了太多在白板技术面试上要求你实现斐波那契数列，你已经受够了。你回家用 Python 写了一个可重用的斐波那契计算器，使用浮点技巧来实现 O(1) 复杂度。

代码很简单：

# fib.py
import math

_SQRT_5 = math.sqrt(5)
_PHI = (1 + _SQRT_5) / 2

def approx_fib(n):
    return round(_PHI**(n+1) / _SQRT_5)

（该斐波那契数列是四舍五入到最接近的整数的几何序列，这是我最喜欢的鲜为人知的数学事实之一。）

作为一个好人，你可以将代码开源，并将它放在 PyPI 上。setup.py 文件很简单：

import setuptools

setuptools.setup(
    name='fib',
    version='2019.1.0',
    description='Fibonacci',
    py_modules=["fib"],
)

但是，没有文档的代码是没有用的。因此，你可以向函数添加 docstring。我最喜欢的 docstring 样式之一是 “Google” 样式。标记很轻量，当它放在源代码中时很好。

def approx_fib(n):
    """
    Approximate Fibonacci sequence

    Args:
        n (int): The place in Fibonacci sequence to approximate

    Returns:
        float: The approximate value in Fibonacci sequence
    """
    # ...

但是函数的文档只是成功的一半。普通文档对于情境化代码用法很重要。在这种情况下，情景是恼人的技术面试。

有一种添加更多文档的方式，专业 Python 人的方式通常是在 docs/ 添加 rst 文件（ reStructuredText 的缩写）。因此 docs/index.rst 文件最终看起来像这样：

Fibonacci
=========

Are you annoyed at tech interviewers asking you to implement
the Fibonacci sequence?
Do you want to have some fun with them?
A simple
:code:`pip install fib`
is all it takes to tell them to,
um,
fib off.

.. automodule:: fib
   :members:

我们完成了，对吧？我们已经将文本放在了文件中。人们应该会看的。

使 Python 文档更漂亮

为了使你的文档看起来更漂亮，你可以利用 Sphinx，它旨在制作漂亮的 Python 文档。这三个 Sphinx 扩展特别有用：

• sphinx.ext.autodoc：从模块内部获取文档
• sphinx.ext.napoleon：支持 Google 样式的 docstring
• sphinx.ext.viewcode：将 ReStructured Text 源码与生成的文档打包在一起

为了告诉 Sphinx 该生成什么以及如何生成，我们在 docs/conf.py 中配置一个辅助文件：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
]
# 该入口点的名称，没有 .rst 扩展名。
# 惯例该名称是 index
master_doc = "index"
# 这些值全部用在生成的文档当中。
# 通常，发布（release）与版本（version）是一样的，
# 但是有时候我们会有带有 rc 标签的发布。
project = "Fib"
copyright = "2019, Moshe Zadka"
author = "Moshe Zadka"
version = release = "2019.1.0"

此文件使我们可以使用所需的所有元数据来发布代码，并注意扩展名（上面的注释说明了方式）。最后，要确保生成我们想要的文档，请使用 Tox 管理虚拟环境以确保我们顺利生成文档：

[tox]
# 默认情况下，`.tox` 是该目录。
# 将其放在非点文件中可以从
# 文件管理器或浏览器的
# 打开对话框中打开生成的文档，
# 这些对话框有时会隐藏点文件。
toxworkdir = {toxinidir}/build/tox

[testenv:docs]
# 从 `docs` 目录内运行 `sphinx`，
# 以确保它不会拾取任何可能进入顶层目录下的
# 虚拟环境或 `build/` 目录下的其他工件的杂散文件。
changedir = docs
# 唯一的依赖关系是 `sphinx`。
# 如果我们使用的是单独打包的扩展程序，
# 我们将在此处指定它们。
# 更好的做法是指定特定版本的 sphinx。
deps =
    sphinx
# 这是用于生成 HTML 的 `sphinx` 命令。
# 在其他情况下，我们可能想生成 PDF 或电子书。
commands =
    sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
# 我们使用 Python 3.7。
# Tox 有时会根据 testenv 的名称尝试自动检测它，
# 但是 `docs` 没有给出有用的线索，因此我们必须明确它。
basepython = python3.7

现在，无论何时运行 Tox，它都会为你的 Python 代码生成漂亮的文档。

在 Python 中写文档很好

作为 Python 开发人员，我们可以使用的工具链很棒。我们可以从 docstring 开始，添加 .rst 文件，然后添加 Sphinx 和 Tox 来为用户美化结果。

你对好的文档有何评价？你还有其他喜欢的方式么？请在评论中分享它们！

via: https://opensource.com/article/19/11/document-python-sphinx

作者：Moshe Zadka 选题：lujun9972 译者：geekpi 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出