蚊章汇 - 文档
type: channel
link: https://linuxcn.bwsl.wang/tag/%E6%96%87%E6%A1%A3/
items: 在 Linux 上用 Doxygen 生成源代码文档
items: DevOps 文档成熟度的四个层次
items: 你喜欢哪种文档标记语言？
items: 编写对社区真正有用的文档
items: 使用 JavaScript 增强你的文档
items: 像书写代码一样撰写文档
items: 文档写作的 DevOps 指南
items: 文档并不是开源项目开发的附属品
items: 编写项目文档时要问自己的 5 个问题
items: 如何使用 Docsify 和 GitHub Pages 创建一个文档网站

在 Linux 上用 Doxygen 生成源代码文档
type: item
date: 2023-09-26T18:33:09+08:00
description: Doxygen 是一款广泛使用的开源文档生成工具，它通过代码注释来生成文档。在试着熟悉别人的代码时，你总希望他们留下的代码注释能对你理解代码有所帮助。同理，无论为了自己还是其他人，编写代码时写注释是好习惯。所有编程语言都有专门的注释语法，注释可以是一个单词、一行文字、甚至是一整段话。编译器或解释器处理源代码时会忽略注释。注释不能完全取代文档，但是有方法可以使用注释来生成文档。Doxygen 是一个开源的文档生成工具，它能够根据代码注释生成 HTML 或 LaTeX 格式的文档。Doxygen 让你在不用额外操作的情况下创建代码结构概览。尽管 Doxygen 主要是用来给 C++ 生成文档的，它对其它语言同样适用，比如 C、Objective-C、 C#、 PHP、Java 和 Python 等。要使用 Doxygen，你只需要在源代码中使用 Doxygen 能够识别的语法来写注释。Doxygen 会扫描源码文件，然后根据这些特殊注释生成 HTML 或 LaTeX 文档。下面的示例项目会演示如何使用 Doxygen 注释，以及文档是如通过注释生成出来的。示例代码可从 GitHub 上获得，本文中也将引用 Doxygen 手册及文档 的相关章节。在 Linux 上安装 Doxygen在 Fedora 上可以通过软件包的形式安装 Doxygen。打开终端运行命令：sudo dnf install doxygen 在基于 Debian 的操作系统上，可以通过以下命令来安装：sudo apt-get install doxygen 使用安装完 Doxygen 后，你需要在项目中按 Doxygen 可以识别的格式来注释代码，还要提供一个 Doxyfile 配置文件来控制 Doxygen 的一些行为。注意：如果你用的是 GitHub 上的示例项目，你可以忽略下面一步。如果 Doxyfile 文件不存在，你可以用 Doxygen 生成一个标准 Doxyfile 模板文件。切换到项目根目录下，运行：doxygen -g 参数 -g 表示 生成 generate 。现在应该会出现一个名为 Doxyfile 的新文件。通过命令调用 Doxygen：doxygen 现在应该能会有两个新文件夹：html/latex/默认情况下，Doxygen 会同时输出 LaTeX 和 HTML 格式的文档。本文主要关注 HTML 文档。你可以在 Doxygen 官方文档的入门小节中找到关于 LaTeX 格式输出的更多信息。双击 html/index.html 打开 HTML 文件。用空的配置文件生成的文档如下图：现在我们试着修改 Doxyfile 文件，并在源代码中添加特殊注释。Doxyfile 文件在 Doxyfile 文件中可以定义大量的可调选项，本文通过介绍示例项目的 Doxyfile 文件我只能覆盖其中很小的子集。第 35 行：项目名称你可以在这里指定项目名称，它最终会显示在 页眉 header 和浏览器标签上。# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by # double-quotes, unless you are using Doxywizard) that should identify the # project for which the documentation is generated. This name is used in the # title of most generated pages and in a few other places. # The default value is: My Project. PROJECT_NAME = "My Project" 第 47 行：项目简介项目简介会以略小的字号显示在页眉上。# Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. PROJECT_BRIEF = "An example of using Doxygen in C++" 第 926 行：包含子目录允许 Doxygen 查找源代码和文档文件时递归遍历子目录。# The RECURSIVE tag can be …

DevOps 文档成熟度的四个层次
type: item
date: 2023-09-16T22:00:09+08:00
description: 提升 DevOps 文档成熟度的过程与达到 DevOps 或 DevSecOps 成熟化的历程是类似的。为了能在软件迭代交付周期内按时交付优质的文档，DevOps 和 DevSecOps 的文档实践也需要是敏捷的。这与实现 DevOps 类似，只是更偏向自动化和敏捷的内容处理方法。如果文档现在才进入你的机构的 DevOps 讨论，那么是时候让文档实践追上 DevOps 的步伐了。下面是 DevOps 文档成熟度的四个层次：第一层：临时且孤立在最低一级成熟度（最不成熟），文档编制工作没有和 DevOps 开发对齐。开发团队和文档团队按照各自的路线开展工作，常常导致文档落后于开发。在竞争激烈的“云”世界里，因为文档问题而推迟产品发布是不可接受的。人员这个阶段的文档编制人员还没有摆脱传统的工作方式。 技术写作 technical writer 人员隶属于一个中心化的单独团队，与开发团队是脱节的。技术写作组和开发团队之间的鸿可能是由多方面原因造成的：造成团队分裂和孤立的公司政治团队只是将技术文档视为项目验收清单上的检查项，而不是推动项目成功的资产事后才雇佣技术写作人员技术写作的优先级与开发团队的实际情况不匹配这个阶段，另一个在人员配置上的挑战是如何“界定工作完成”。刚接触敏捷实践的技术写作可能难以适应 CI/CD 工具链和流程。文档工具和流程这个阶段的技术写作仍习惯于使用传统的办公工具，比如办公套件和布局程序。这些工具不够敏捷，没有版本控制和内容管理的要求。它们无法与 DevOps 工具链高效集成，不能支撑快速开发。在这个成熟度，技术写作仍然参照遗留的模板和流程。成果这个级别交付的文档可能是过时的，甚至缺乏技术准确性的。如果开发团队以 DevOps 的速度推进工作，而技术文档编制却遵循传统的非敏捷流程（使用专有的工具和交付格式），这就很难让文档迭代速度并跟上应用程序的变化。第二层：实验和试点DevOps 文档成熟度的第二层是实验/试验阶段。这个阶段是 DevOps 团队主管和技术写作采取行动打造更敏捷的文档实践和工具的第一步。理想的情况下，这些实验是 相关方 stakeholder 支持的试点项目的一部分。他们能够从文档交付流程的改善以及其与 DevOps 实践的集成中获益。人员本阶段的人员可能来自以下三种形式：有远见的技术写作为了更好地完成工作，用自己的时间来实验更敏捷的工具。并且向领导层提出更敏捷的文档编制过程的想法。DevOps 负责人或工程师试用 Hugo 和 Jekyll 等工具，并将这些工具集成到 CI/CD 流水线中。然后 DevOps 小组教授技术写作如何使用它们。团队引入了第三方承包商或顾问，他们在 DevOps 文档工具方面具有专业知识，并且了解文档工具适合嵌入到 CI/CD 工具链和 DevOps 生命周期的位置。文档工具和实践Hugo 和 Jekyll 是本阶段开始出现的工具。在这个阶段也出现新的内容策略和技术写作方法。成果实验试点阶段理想的成果应该能够“ 落地并推广 land and expand ”。也就是说其它项目组也可以将其付诸实践。这个阶段的实验也包括内容策略和发布流程上的根本性变化。其它非试点项目组的技术写作可以学习和使用它们。试点带来的另一个可能的产出是 技术写作招聘流程 的变化。你需要针对 DevOps 和你新引入的文档工具对内部编写人员进行培训。新的文档工具和流程是此阶段的关键成果，你需要通过演示、状态报告和内部案例研究等方式，将这一成果推给领导层、相关方和其它团队。第三层：部分自动化和扩展DevOps 文档成熟度的第三层（部分自动化和扩展）就是“落地并推广”的进一步行动。在这个阶段，其它 DevOps 团队借用试点项目中产生的 DevOps 文档工具和流程，吸取其中的经验教训。人员在这个成熟度，技术写作和 DevOps 团队开始更紧密的协作。招聘新的技术写作主要关注具有 DevOps 环境经验的人选。工具和文档实践技术写作开始从抛弃传统的工具和流程，转到更敏捷的文档工具上，比如：docToolchainDocbookHugoJekyll在这个成熟度，技术写作也负责调整遗留的文档实践。成果DevOps 文档工具和实践超越试点项目，成为标准实践。在这个成熟度，随着新团队使用新的文档工具和流程，持续学习是必不可少的。第四层：完全采用在最高一级的 DevOps 文档成熟度（完全采用且自动化）所有工具、实践和流程已经到位，以支持将文档为项目中的高优先级事项。要达到这一成熟度，需要不断实验、迭代和团队协作。人员完全自动化使 DevOps 团队与技术写作之间的协作更紧密。这一阶段的标志是，技术写作牢牢地融入到项目团队的工作流程中。文档工具的维护工作由一些大型企业负责，它们拥有专职维护 DevOps 工具链…

你喜欢哪种文档标记语言？
type: item
date: 2023-08-08T06:51:27+08:00
description: 文档对于开源软件项目至关重要。我们询问了我们的贡献者，他们在文档编写中最喜欢使用的标记语言是什么。文档很重要，而易读的文档更重要。在开源软件世界中，文档可以告诉我们如何使用或贡献一个应用程序，就像 游戏 的规则书一样。有很多不同类型的文档：教程操作指南参考指南软件架构产品手册我们向一些贡献者询问了他们的技术文档工作流程，他们更喜欢使用哪种标记语言，以及为什么会选择其中一种。以下是他们的回答。AsciiDoc过去几年中，Markdown 一直是我的标准语言。但最近我决定尝试一下 AsciiDoc 。这种语法并不难，我在 Linux 桌面上的 Gedit 就支持它。我计划暂时坚持使用它一段时间。—- Alan Formy-Duval就低语法标记语言而言，我更喜欢 AsciiDoc。我喜欢它，是因为其转换过程一致且可预测，没有令人困惑的“口味”变化 。我还喜欢将它输出为 Docbook，这是一种我信任其持久性和灵活性的标记语言，它有大量的语法标记。但“正确”的选择往往取决于项目已经在使用什么。如果项目使用某种口味的 Markdown，我就不会使用 AsciiDoc。嗯，公平地说，我可能会使用 AsciiDoc，然后使用 Pandoc 将其转换为草莓味的 Markdown。当然，我认为 Markdown 有其应用的时间和场合。我发现它比 AsciiDoc 更易读。AsciiDoc 中的链接是这样：http://example.com [Example website] 而 Markdown 中的链接是这样：[Example.com](http://example.com) Markdown 的语法直观，以读取 HTML 的方式呈现信息，大多数人都以相同的方式解析此类数据（“Example website……哦，那是蓝色的文本，我将悬停一下以查看它指向哪里……它指向 example.com”）。换句话说，当我的受众是人类读者时，我通常会选择 Markdown，因为它的语法简单，但仍具有足够的语法可以进行转换，因此仍然是一种可接受的存储格式。虽然像 AsciiDoc 这样简洁的语法看起来更令人吃惊，但如果我的受众是要解析文件的计算机，我会选择 AsciiDoc。—- Seth KenlonreStructuredText我是 代码即文档 的忠实支持者，它将开发者工具融入到内容流程中。这样可以更轻松地进行高效的审查和协作，尤其是如果工程师是贡献者。作为一个标记语言的行家，我在 O'Reilly 写了整整一本关于 AsciiDoc 的书，还使用 Markdown 在各个平台上发布了上千篇博文。但目前，我转向使用 reStructuredText，并维护一些相关工具。—— Lorna Mitchell不得不提到 reStructuredText。在我大量使用 Python 编程时，它已成为我的首选。它也是 Python 长期以来用于文档源码和代码注释的标准。与 Markdown 相比，我喜欢它不会受到非标准规范的困扰。话虽如此，当我处理更复杂的文档时，确实还得使用许多 Sphinx 的功能和扩展。—— Jeremy StanleyHTML能不用标记语言我就不用。不过，我发现 HTML 比其他标记语言更易于使用。—— Rikard Grossman-Nielsen对我来说，撰写文档有各种方式。这取决于文档将要放在何处，是作为网站的一部分、软件包的一部分，还是可下载的内容。对于 Scribus 来说，其内部文档采用 HTML 格式，因为需要使用内部浏览器来访问。对于网站，可能需要使用维基语言。而对于可下载的内容，可以创建 PDF 或 EPUB 格式。我倾向于在纯文本编辑器中编写文档。我可能会使用 XHTML，以便将这些文件导入到像 Sigil 这样的 EPUB 制作工具中。当然，对于创建 PDF，我会使用 Scribus，虽然我可能会导入用文本编辑器创建的文本文件。Scribus 具有包含图形并精确控制其布局的优势。Markdown 从未吸引我，我也从未尝试过 AsciiDoc。—— Greg Pittman我目前正在使用 HTML 撰写大量文档，所以我要为 HTML 代言一下。你可以使用 HTML 创建网站或创建文档。请注意，这两者实际上并不相同 —— 当你创建网站时，大多数设计师关注的是呈现。但是当你编写文档时，技术作者应该专注于内容。当我用 HTML 撰写文档时，我遵循 HTML 定义的标签和元素，并不关心它的外观。换句话说，我用“未经样式化”的 HTML 编写文档。稍后我总是可以添加样式表。因此，如果我需要强调文本的某一部分（比如警告），或者给单词或短语加重语气，我可能会使用 和 标签，像这样： 警告：激光！不要用你剩下的那只眼睛看向激光。…

编写对社区真正有用的文档
type: item
date: 2023-04-23T01:28:00+08:00
description: 建立良好的文档可能是困难的，但它对有效的沟通至关重要。遵循这个框架来编写并与正确的人分享文档。成功和可持续的项目，与那些消失无踪的项目有什么不同？答案是 —— 社区。社区是开源项目的发展动力，而文档是构建社区的基石之一。也就是说，文档的意义不仅仅在于文档本身。建立好的文档可能很困难。用户不愿意阅读文档，因为它不易查找，它很快就过时了，它冗长，或者它不全面。开发团队不写文档，因为他们陷入了“对我来说显而易见，所以对所有人都显而易见”的陷阱。他们不写，因为他们忙于开发项目。要么是需求变化太快了，要么是开发得还不够快。但是好的文档仍然是团队和项目之间最好的沟通工具。考虑到项目随着时间的推移往往会变得更大，这一点尤其重要。文档可以是团队或公司内部的唯一真理。这在协调人们朝着共同的目标前进，以及在人们转移到不同的项目时保留知识方面非常重要。那么，要如何为一个项目写出合适的文档，并与正确的人分享呢？什么是成功的社区文档？要想在你的社区文档编写中取得成功，你需要：规划你的路径使其清晰简单灵活变通，根据具体情况调整路径做版本控制灵活并不意味着混乱。许多项目之所以成功，就是因为它们组织得很好。James Clear（《 原子习惯 Atomic Habits 》一书的作者）写道：“你并不是提升到了你目标所在的水平，而是降低到你整个系统所在的水平。”一定要组织好过程，使水平足够高，才能取得成功。设计流程文档本身就是一个项目。你可以把写文档当作写代码一样。事实上，文档可以是一个产品，而且是一个非常有价值的产品。这就意味着你可以采用与软件开发相同的流程：分析、获取需求、设计、实现和维护，把文档作为你的一个流程对待。在设计流程时，要从不同的角度考虑。不是所有的文档都适用于所有人。大多数用户只需要一个了解项目概况的文档，而 API 文档则是留给开发者或高级用户的。开发者需要了解库和函数的文档。用户则更需要看到示例、操作指南，和项目与其他软件相配合的架构概述。总之，在创建任何流程之前，你必须确定你需要什么：关注的群体： 包括开发者、集成商、管理员、用户、销售、运营、高管专业水平： 要考虑到初级、中级和高级用户详细程度： 既要有高层级的概述，也要有技术细节，所以要考虑如何呈现这些内容路径和入口： 人们如何找到文档，如何使用文档当你思考这些问题时，它可以帮助你构建你想通过文档传达的信息的结构。它定义了文档中必须包含的内容的清晰指标。下面是如何围绕文档建立一个流程的方法。编码约定代码本身应该有意义。文档应通过良好的类名、文件名等来表达出来。通过思考以下内容，创建通用的编码标准和自我注解的编码过程：变量命名约定通过使用类、函数命名方案使名称易于理解避免深度嵌套，或 根本不嵌套不要简单地复制和粘贴代码不应使用长方法避免使用幻数（改用常量）使用提取的方法、变量等使用有意义的目录结构、模块、包和文件名开发时测试测试不仅仅是关于代码应该如何工作。它还涉及如何使用 API、函数、方法等。编写良好的测试可以揭示基本用例和边缘用例。甚至还有一种 测试驱动开发 的实践，专注于在代码开发之前创建测试用例（应该测试什么以及如何测试的分步场景）。版本控制版本控制（即使是对文档进行版本控制）可以帮助你跟踪更改的逻辑。它可以帮助你回答为什么这么修改。确保提交期间的注释能解释为什么进行更改，而不是进行了哪些更改。编写文档过程越吸引人，就会有更多的人参与其中，为它添加创造力和乐趣。你应该通过以下方式考虑文档的可读性：软件代码约定图表和图形（也通过文字进行解释）思维导图概念图信息图表图片（突出显示重要的部分）短视频通过使用不同的交流方式，你可以提供更多的方式来参与文档。这有助于防止误解（不同的语言，不同的含义）和有助于通过不同的学习方式进行学习。以下是一些用于创建文档的软件工具：Javadoc、Doxygen、JsDoc 等： 许多语言都有自动化的文档工具，以帮助捕获代码中的主要功能Web 钩子和 CI/CD 引擎： 允许持续发布文档Restructured Text、Markdown、Asciidoc： 文件格式和处理引擎，帮助你从纯文本文件中生成美观且实用的文档ReadTheDocs： 是一个可以和公共 Git 存储库联动的文档托管主机Draw.io、LibreOffice Draw、Dia： 制作图表、图形、思维导图、路线图、计划、标准和指标等Peek、Asciinema： 记录终端命令操作VokoscreenNG： 录制屏幕和鼠标点击操作文档很重要编写文档的过程和协议与项目本身同样重要。最重要的是，它把项目的信息和项目的创造传达到位，更加令人兴奋。快速进入项目和流程，以及了解一切是如何工作的，是文档一个重要的功能。它有助于确保众人持续参与。通过在团队中构建一种“语言”，可以简化流程，更清晰…

使用 JavaScript 增强你的文档
type: item
date: 2022-12-23T18:06:22+08:00
description: 让你的开源项目文档充满活力，从而吸引各种经验水平的用户。开源软件项目通常拥有非常多样化的用户人群。有些用户非常擅长使用该系统，并且只需要很少的文档。对于这些实力派用户，文档只需要提供必要的提示，并且可以包含更多的技术信息，比如说在 Shell 中运行的命令行。有些用户可能只是初学者。这些用户需要更多的帮助来设置系统并学习如何使用它。写一个同时适合这两个用户群体的文档是令人生畏的。网站文档需要在 “提供详细的技术信息” 和 “提供更多的概述和指导” 之间寻求一个平衡。这是一个很难找到的平衡。如果你的文档不能同时满足这两个用户人群，那么考虑一下另外一个选择 —— 动态文档。探索在网页中添加一点 JavaScript 使用户可以选择自己想看的内容。构建你的内容你可以把例程添加的你的文档中需要同时满足 专家 expert 和 初学者 novice 的地方。在这个例程中，我们可以使用一个虚构的名为 AwesmeProject 的音乐播放器。你可以用 HTML 编写一个简短的安装文档，通过 HTML 的 类 class 功能同时为专家和初学者提供操作指南。例如，你可以用下面的代码来为专家定义一个段落： 这同时指派了 “专家类” 和 “读者类”。你可以用下面的代码来为初学者创建一个相同的段落。 完整的 HTML 文件同时包含初学者的段落和专家的段落。 How to install the software How to install the software Thanks for installing AwesomeProject! With AwesomeProject, you can manage your music collection like a wizard. But first, we need to install it: You can install AwesomeProject from source. Download the tar file, extract it, then run: ./configure ; make ; make install AwesomeProject is available in most Linux distributions. Check your graphical package manager and search for AwesomeProject to install it. 例子中的 HTML 文档没有与之关联的样式表，所以浏览器中会显示所有的段落。我们可在文档中添加一些简单的样式来为 读者 reader 、 专家 expert 或者 初学者 novice 突出任何元素。为了使不同的文本更容易区分，让我们把读者类的背景颜色设置成米白色，专家类的字体颜色设置为深红色，初学者的字体颜色则设置为深蓝色。 How to install the software How to install the software 当你在浏览器中查看这个网页时，这些样式有助于突出这两个段落。安装指导的所有段落都有一个米白色背景，因为他们都有 读者 reader 这个类。第一个段落的字体是深红色的，这是由 专家 expert 这个类定义的。第二个段落的字体是深蓝色的，则是由 初学者 novice 这个类定义的。添加 JavaScript 控件这些类的应用，使你可以添加一些简单的 JavaScript 函数，只显示其中一个内容块。一个方法是，首先给所有的读者类元素设置 display:none 。这会将内容隐藏，使其不会在页面上显示。然后，用函数将你想显示的类元素设置为 display:block : 要在 HTML 文档中使用这个 JavaScript，你可以吧这个功能附加到一个按钮上。由于 readerview 函数需要一个 听众 audience （这应该是相对那个虚拟音乐播放器来说的）作为参数，你可以使用你想查看的听众类别来调用这个函数，可以是 读者 reader ， 专家 expert 或者 初学者 novice 。 How to install the software How to install the software view novice text view expert text Thanks for installing AwesomeProject! With AwesomeProject, you can manage your music collection like a wizard. But first, we need to install it: You can install AwesomeProject from source. Down…

像书写代码一样撰写文档
type: item
date: 2022-12-20T05:58:02+08:00
description: 不想让文档成为事后的想法？或许你该尝试一下全新的写作方式。很多工程师与手工艺者都对他们使用的工具有特别的要求。为了顺利的完成工作，你需要最好的工具和使用它们的技巧。软件开发中最好的工具在应用到其他的数字创作领域中也可以是很强大的。 文档即代码 Docs as Code 的方式就是很好的例子。“文档即代码”意味着使用与代码开发相同的工具和工作流来撰写文档。文档即代码的支持者认为，这样的方式可以在降低写作者的工作量的同时，也带来了更好的文档。文本格式与源文件控制从传统的写作平台切换到文档即代码方式时，最主要的调整是将写作内容保存在基于文本的标记格式中。这一转变使得基于纯文本的工具都适用于文档写作。无论你选择 DocBook、Markdown 或者其他的标记语言，从只使用一种工具到使用一种标准格式配合多种工具是一种巨大的转变。找到支持你的工作流程的工具是非常重要的。很多开发者在文档即代码项目中使用他们的 代码编辑器。因为他们已经是这些工具的高阶用户，一切都很顺利。而找到适合团队里其他专业人员，比如技术撰稿、编辑、信息架构师和文档产品责任人的工具可能需要一番努力。这里有一些选项可供参考：各种 优秀的 Markdown 编辑器 之一附带良好的预览工具的代码编辑器可能更适合非程序员流行的 Git 托管服务的网页界面尤其适用于偶尔有需要的贡献者一旦内容以标记语言的格式安全地保存，就可以使用 Git 这样的版本控制进行管理。Git 相比大多数文档平台具有更多的功能：清晰详细的文档版本历史：谁在什么时候改变了什么。如果你有良好的提交信息惯例，你甚至可以了解到为什么会有这样的变更。简明的并行修改过程。在 Git 中使用分支工作意味着任何人可以做出他们想要的任何改变，并在最后合并所做的变更。先进的协作与审查工具。所有的源代码管理平台都被设计成支持详细审查每一个变更，并根据需要进行讨论，使每个人都确信这个变更可以继续进行。自动质量检查，比如拼写检查和链接检查。这不仅节省了时间，而且可以发现可能遗漏的错误。源代码管理有很多优点。但要记住，如果你准备入门源代码管理，它有一定的学习曲线。这是一些有助于撰写者入门的优秀的 学习资源 和 文章。你也可以让具有好奇心的文档撰写者自行寻找对他们有用的学习材料，而不是请你的工程师来培训他们。（问我是怎么学会的？ —— 当然是通过艰苦的方式！）拉取请求和评审循环所有的源代码管理平台都围绕 拉取请求 Pull Request 这一概念设计的，这有时也称为 合并请求Merge Request：有时候，某个人或某个团队先将一系列改变整合到一起，然后请求把这些修改拉到主项目中。不过从许多方面来说，在文档中一次处理多个变更比在代码中更容易。改变一篇文章中的某个地方，比更改代码并发现有其它几个地方依赖它，副作用更小。最强大的协作工具是 diff，它可以通过一个易于理解的方式展示旧版本与新版本之间的差异。该工具有许多不同的版本，可以使比较视图更易于查看：双栏模式、行内模式，甚至是渲染过的 Markdown 模式。团队中的每一个成员都可以选择最适合他们的工具。举例而言，网页视图通常用于查看细微变更，而对于更大的变更，我习惯于使用 vimdiff 或 Meld 在本地浏览。评审意见可以被添加到整个修改中，也可以添加到拟议的变更的个别行中。一些项目限制了行的最大长度，即硬换行，或者一行一句，以使得向文本的特定的部分添加注释更加容易。可以添加进一步的修改与评论，直到审查过程结束，修改被接受。由于拉取请求在项目仓库以队列形式展示，这是一种很好的方式，可以展示目前正在进行的任务以及需要进行检查操作的任务。diff 工具使得评审人员更方便地添加他们的思考。尤其是你在与技术受众工作时，你可以通过他们日常使用的工具获得来自他们的评论。持续集成与部署以纯文本形式提供你的文档的源代码有很多益处，你可以轻易找到每一个需要修改的位置，你可以使用现有的诸如 wc、grep 或 tree 之类的工具，来处理潜在的大型文档集。当你将这些与源代码管理平台结合起来之后，你可能获得更多的可用工具，并且它们都是开源的。另一个工作流程上的巨大提升是持续部署的能力。简单来说，这意味着，每当一个拉取请求被合并到主项目中，项目可以直接自动化部署到位。如果这个变更足够好，就可以放进项目中，它也足够好到可以在放到文档网站上帮助你的读者。典型情况下，持续部署是配置在一台单独的自动化服务器上的，比如 Jenkins 或者 Git 钩子。不论哪种方式，基于文本的标记语言与文档即代码平台（通常是静态网页生成器，比如 Hugo 或 Sphinx）结合来生成文档网站，然后自动部署。在部署之前，同样的自动化流程可以被用于对将要合并的拉取请求进行检查。在一个编程项目中，通过计算机自行进行代码检查、代…

文档写作的 DevOps 指南
type: item
date: 2022-12-15T18:15:40+08:00
description: 将文档写作加入到 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 利益相关者和从业者都很有吸引力。在自动化中断之前，一切都很有趣。拥有自动化运行手册、管理指南和其他内容的文档（并且是最新的）意味着无论何时发生故障，…

文档并不是开源项目开发的附属品
type: item
date: 2022-05-05T17:00:04+08:00
description: 有些项目长期保持活跃，有些项目却过早消亡 —— 这两者的区别往往在于它们的文档。严谨、聪明的文档可以给你的项目带来它所需要的动力。你应该把文档工作视为一项主要工作，把它与开发相提并论，下面我将说明这么做的理由和正确的做法。经常会有开发者简单地认为他们的代码的“ 自我描述 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 这样的文档平台会提供合适的反馈服务，这有助于验证文档是否有用。始终寻求 主题专家 subje…

编写项目文档时要问自己的 5 个问题
type: item
date: 2020-10-07T06:32:10+08:00
description: 使用有效沟通的一些基本原则可以帮助你创建与你的品牌一致的、编写良好、内容丰富的项目文档。在开始实际撰写又一个开源项目的文档之前，甚至在采访专家之前，最好回答一些有关新文档的高级问题。著名的传播理论家 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 创建一个文档网站
type: item
date: 2020-09-02T05:17:00+08:00
description: 使用 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 有两种方法：通过 NPM 安装 Docsify 的命令行界面（CLI）。手动编写自己的 index.html。Docsify 推荐使用 NPM 方式，但我将使用第二种方案。如果你想使用 NPM，请按照快速入门指南中的说明进行操作。从 GitHub 下载示例内容我已经在该项目的 GitHub 页面上发布了这个例子的源代码。你可以单独下载这些文件，也可以通过以下方式克隆这个存储库。git clone https://github.com/bryantson/OpensourceDotComDemos 然后 cd 进入 DocsifyDemo 目录。我将在下面为你介绍这些代码，它们克隆自我的示例存储库中，这样你就可以理解如何修改 Docsify。如果你愿意，你也可以从头开始创建一个新的 index.html 文件，就像 Docsify 文档中的的示例一样： 探索 Docsify 如何工作如果你克隆了我的 GitHub 存储库，并切换到 DocsifyDemo 目录下，你应该看到这样的文件结构：文件/文件夹名称内容index.html主要的 Docsify 初始化文件，也是最重要的文件_sidebar.md生成导航README.md你的文档根目录下的默认 Markdown 文件images包含了 README.md 中的示例 .jpg 图片其它目录和文件包含可导航的 Markdown 文件index.html 是 Docsify 可以工作的唯一要求。打开该文件，你可以查看其内容： Docsify Demo 这本质上只是一个普通的 HTML 文件，但看看这两行： ... 一些其它内容 ... 这些行使用内容交付网络（CDN）的 URL 来提供 CSS 和 JavaScript 脚本，以将网站转化为 Docsify 网站。只要你包含这些行，你就可以把你的普通 GitHub 页面变成 Docsify 页面。 标签后的第一行指定了要渲染的内容： Docsify 使用单页应用（SPA）的方式来渲染请求的页面，而不是刷新一个全新的页面。最后，看看 在这个块中：el 属性基本上是说：“嘿，这就是我要找的 id，所以找到它并在那里呈现。”改变 repo 值，以确定当用户点击右上角的 GitHub 图标时，会被重定向到哪个页面。 将 loadSideBar 设置为 true 将使 Docsify 查找包含导航链接的 _sidebar.md 文件。你可以在 Docsify 文档的配置部分找到所有选项。接下来，看看 _sidebar.md 文件。因为你在 index.html 中设置了 loadSidebar 属性值为 true，所以 Docsify 会查找 _sidebar.md 文件，并根据其内容生成导航文件。示例存储库中的 _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” 等链接是缩进的；这意味着它们被渲染为父链接下的子链接…