如何写好开源文档~看完助你轻松上手！

时间：2023-05-25 00:51:01 | 来源：网站运营

时间：2023-05-25 00:51:01 来源：网站运营

如何写好开源文档~看完助你轻松上手！：开源项目下，代码解决技术问题，而文档则帮助你使用这些代码。
对于很多人来说，开源项目中的文档对于使用开源代码起到了关键的作用，也是许多技术爱好者较为关注的内容，技术爱好者通过文档学习使用开源代码，也可以通过文档指导去贡献代码。
那么对于专门服务开源产品下的技术文档工程师，与其他行业的技术文档工程师，工作中，有哪些不同点和相同点呢？
首先我们先了解一下开源行业有哪些特点。
开源行业特点是什么？
软件的“源”即其源代码，“开源”的核心概念是软件的编写者将源代码免费提供给使用者，同时要求使用者遵循一定的开源规范。开放源代码促进会（Open Source Initiative，缩写：OSI）是一个旨在推动开源软件发展的非盈利组织。OSI 组织在规范了开源项目和软件的开源要求以外，也在开源许可（open source license）上满足关于源代码的使用和修改、关于软件传播以及公平性、中立性等方面的诸多要求，这些要求加强了开源产业的规范性，构建了诸多开源商业模式的基础。
我们所熟悉的一些开源行业类似于Linux Kernel, Git, MySQL等，他们代码开源，技术工程师齐力贡献代码，现在成为了开源界的Top行业。
其实开源行业还是有很显著的特点的，从而让很多技术行业趋之若鹜：

• 自由性：开源的发起者可以是个人、企业等各种主体；开源与商业化并不矛盾，开源软件的“引流”作用能够帮助企业或个体实现周边产品的增收、市场影响力的提升以及产业生态的协同构建。
• 开放式协作：源代码自由的被访问，技术爱好者共同改进代码，协同合作，资源透明，可以自行追踪代码更新，无需跟进或被绑定到某个产品的服务中。
• 专业可靠：开源代码的存在时间可以超越其原作者对它更新的时间，活跃的开源社区帮助代码进行不断地更新。开放标准和同行评审可以确保开源代码可以经常得到适当的测试。
• 灵活性：由于开源代码可灵活修改，因此您可以使用它来解决您的业务或社区面临的独特问题。您无需只使用一种特定方式使用代码，您可以依托社区帮助和同行评审帮助您实施新解决方案。
• 成本更低：源代码公开免费，可以跟进代码更新，也可以进行二次开发。

开源行业文档的特点是什么？


在开源软件代码飞速发展的情况下，随之对开源代码使用和技术解释的开源文档也面临一些挑战。其实开源行业文档和闭源行业的文档有一些共通性，但是也有一些差异点，开源行业的文档特点比较鲜明：

• 文档受众：开源行业文档它的主要面向受众就是首先是开发者，他们关注软件如何安装部署调试以及对其进行二次开发；其次是友商或者竞商，他们关注软件使用难易度，定制化服务成本，优化空间，是否可以直接选用，对其他工具依赖度高不高等等。
• 协作方式：开源文档写作的协作方式更为开放，开源公司的技术文档工程师是主要写作者，但是他的协作者可以是公司内部同事，也可以是贡献代码的技术爱好者，也可以是其他公司的技术写作同行，协作对象面向大众。
• 文档载体：以网页的形式展示文档内容。区别于传统文档，承载传统文档的媒介主要是PDF/纸质文档，.chm 格式的帮助文档。开源行业的文档形式更为丰富，但是它主要是以响应式网页的形式承载文档。
• 发布周期：开源文档发布周期非常灵活，即更新即发布，当然不同的开源公司的文档在发布的流程中设有一些时间卡点，以保证最新代码与最新文档能保持同期更新。
• 更低成本：文档可以通过文档构建平台直接承载，并发布为网页。

开源行业技术文档工程师的价值是什么？


作为一个技术文档工程师，无论服务于什么行业，无论写什么产品的文档，基本的核心都是不变的。例如你必须有用户分析的能力、任务分析的能力、沟通能力、文档工具链的使用能力、流程管理能力以及质量管控的能力。即便是没有开源文档经验的各位技术文档写作者，也可以借鉴很多闭源产品的写作经验。
开源行业文档工作评价体系与闭源行业文档稍有不同，最大的区别是对于用户问题的响应速度非常快。我们在考察开源文档工程师 KPI 时或者获取最直接用户体验的时候，相应的数据也更加直观。

• KPI考核：那么如何去考核一个开源文档工程师的KPI呢，一般情况下，可以最直接的在 Git 上检查提交的 PR 的数量和质量，以及解决 Issue 的数量，在社区的活跃度也可以充分体现日常文档工作。 Issue 的解决方案也可以看得出来是解决了文档的 bug 还是助推了产品的优化，多维度评价一个文档工程师的工作价值。
• 降本增效：开源文档同代码一样，直接面向大众，技术爱好者会直接贡献代码和文档到 Git，他们遇到的问题也会直接反应到 Git 的 Issue 里，你直接面对这些问题，而文档就是去帮助他们去解决问题的，节省了很多需要特意去做调查问卷或者去做用户访谈去挖掘问题的时间，也能迅速响应这些问题，无论是你的文档本身去响应这些问题，还是技术工程师去响应问题，问题的产生，问题的记录，以及问题的解决，答案的记录，都可以形成文档，帮助开源企业降本增效。
• 用户行为采集与分析：对文档网站做埋点，可以采集到开源文档社区用户行为，并产生分析报告。你可以让前端工程师帮忙在文档社区或者文档网站上做埋点，引入 Google Analytics 或者其他用户分析模式，通过对网站流量（主要是从：独立访问者数量（unique visitors，UV）、重复访问者数量（repeat visitors）、页面浏览数（page views，PV）、每个访问者的页面浏览数（page views per user）这几个维度）数据的分析，以及对用户行为（用户的来源网站、用户的搜索引擎和关键字、用户在该网站上的停留时间、不同时间段的用户访问量、用户的浏览的设备类型、用户的浏览器的名称和版本、用户的屏幕分辨率、用户的操作系统名称和版本、用户所在地理区域分布）进行分析，提取关键信息，优化文档质量。这些数据非常真实，你可以通过这些数据，去思考如何去调整文档结构，定位文档属性，为你的用户提供什么帮助，解决什么问题，更好的去运营你的文档社区。
• 用户转化率：一部分技术爱好者都是通过产品的介绍，软件使用的介绍选择去试用开源产品，如果文档帮助他们解决了技术上的难题，那么迅速将转化为深度用户，反之，会失去一部分技术爱好者的贡献度。另外一部分技术爱好者，是产品运营吸引过来，试用开源产品，阅读文档寻找解决方案进而转化为深度用户的。开源文档它对技术的描述和指导更加详尽，它的阅读量和起到的作用是非常大的。你可能在使用某些指令进行操作的时候，遇到了困难，不用在网络上搜索海量的答案，并反复验证测试，你可以参考直接文档，也可以直接提交问题给开源产品，你得到答案也很快。它区别于闭源产品，闭源产品面对技术问题或业务问题时，可能反馈给你的答案是邮件或者其他工单报告，体现在文档中可能需要等到产品GA，而开源社区随时都可以回答你的问题。开源产品本身也可以为其开源文档引流，吸引大批技术爱好者参与代码或文档贡献。

总之，对于用户的反馈，开源文档社区的速度都是很快的，我们可以跟我们的用户直接面对面。


开源行业技术文档工程师的技能树


我们从 tcworld 2022 年技术传播大会上曾奕霖的分享上截取了部分内容，非常有价值，为我们开源行业的文档工程师的技能培养提供了方向。
他在大会中将技能树分为基础版，进阶版和高级版，在文档工程师本职技术写作的基础上，提出了其他的需要具备的能力。


基础版


既然是给开源产品写文档，那么对于文档工程师基础能力除了最基础的制图能力（即画图，制表，以及处理图片），还需要有 Doc as code 的写作能力。
如何理解 Doc as code 的写作能力，结合下图，从 Git basics 和 CLI basics 开始看，你需要掌握 Git 指令，会执行一些本地命令，并且你可以熟练使用 Markdown 或 XML 进行文档写作。

进阶版


那么在基础版的基础上，文档工程师有需要增加更多的技能。
你必须学会在写作过程中发现问题并解决问题，这不仅包括对文档的测试，也包括在编写技术难点时，能自己通过操作代码去执行一些测试，发现问题，并解决问题，或者助推代码进行优化更新。
另外就是对于一些常用的命令行，无论是 Git 指令还是本地测试指令，需要给自己的简单的代码能力做一个提升。



高级版


现在我们技术文档工程师的技能树需要提升到高级版，那么会面临什么样的挑战呢？
其实也是我们对技术能够继续保持热爱并且能真的愿意深入了解技术，自我驱动去研究技术，虽然对技术文档工程师的代码能力没有硬性的要求，但是我们如果掌握了一定的测试技巧，数据分析或者文档模板管理，自动化文档测试或发布流程的话，对我们来说，不仅仅是能力提升，还让我们对我们整个产品的技术框架、对我们文档所依托的的整个技术框架，有了更清晰的理解和认识，我们不会再仅仅沉浸于写作本身，而是对整个产品或者整个产品文档也会有更全局观的认识，才能不断地驱动文档质量做出提升。
另外通过全局观，你也可以对产品提出优化建议，你是直观感受用户体验好与差的人，文档可以让你在阅读或者写作时，真正站在用户角度思考产品。


你可以试着驱动自己对技术点的测试能力，对文档阅读量做数据分析，对文档架构或者未来规划有全局观的认识，对改造文档网站样式、布局做出新的规划，对于文档整个开发流程中提出自动化建议。



推荐的一些工具和软件




一般写开源文档的工作流



写作工具推荐：

一般情况来说，开源行业技术文档工程师平时写作的文档类型和写作的语法一般是markdown，主要是为了快速写作，不再关注文档的格式，“把文档渲染得漂亮”这部分工作交给设计师，交给前端工程师，而我们把我们的主要精力放在我们输出内容是否准确，用户体验是否友好上面。
我们推荐一些适合平时文档写作一些比较典型的 Markdown 编辑器。

• Visual Studio Code： 对于使用 Visual Studio Code 的同学，也可以使用一些辅助的插件，比如实时预览或者安装汉化包：

Markdown preview Github Styling
Markdown All in One
Chinese 中文包

• Typora
• Atom（软件已停止升级，但是可以下载使用）
• Mark Text/Notable/Sublime Text /Trilium

文档源码托管平台推荐：
一般开源公司是代码托管在哪里，文档也托管在哪里，类似于CMS。有一些开源公司文档中心还没有成型，一直放在公司内部的 wiki 站点，需要把文档整合到托管平台，那么我们优先考虑跟代码托管的平台放在同一个地方，从代码引流，让更多的技术爱好者关注我们的文档。一般情况下，代码托管的平台主要是：gitee/gitlab/github/gitshell。
有个稳定源码的托管平台，那么我们还可以引入一个文档网站生成的框架，让技术同学做技术支持，把结构化的文档源码搭建成为文档网站，我们推荐一些典型的开源文档框架：readthedocs/mkdocs/docusaurus。
我们也可以在写作文档的过程中，使用一些脚本工具检查文档内容是否正确，可以结合公司的文档框架，让开发同学帮忙写一些脚本工具，嵌入到托管平台中，自动校验文档的正确性。例如可以开发一些检查坏链的脚本工具 Broken link checker，或者检查是否有冗余空行的脚本工具Blank checker。







参考文献和作者

参考来源	参考内容	原作者
tcworld 2022 年技术传播大会	《文档工程师的开源体验、技能树和工具分享》	曾奕霖
维基百科	开源软件介绍