如何写出一份合格的技术文档

2023-04-06 20:05| 来源: 网络整理| 查看: 265

原文地址

如何坚持写技术博客？ (opens new window)

# 1. 引言

写技术文档是大部分程序员都很想坚持却又总是断断续续的一件事。大家愿意写技术文档是因为有很多好处，例如：

有助于整理平常的思考、梳理一个复杂难懂的技术细节；同时也可以满足分享与传播的欲望，幸运的话还能提升自己的 impact。

为了能长久地坚持写技术文档，不让写技术文档成为一件麻烦事而丧失了写作的动力，需要做一定的工作来破除阻碍我们坚持写博客的障碍：

1. 排版规范化：排版规范化可以帮助我这种强迫症不必要纠结具体的格式，参考先进的排版规范会大大提高我们文章的可读性；

2. 选题系统化：技术博客说来说去也就是几种常见的内容类型，不同类型对应不同的场景与写作需求，需要我们花费不同的时间去完成。做一下简单的梳理帮助我们不必要苦恼内容的来源与分类；

3. 维护简单化：从功利的角度来讲，除非你是前端工程师，否则你的博客做得再花哨也不会为你的面试加分多少。理想的模式是我们只负责内容，技术文档的编译、发布、运行都交由第三方工具和服务商来完成。

# 2. 排版规范化 # 2.1 空格行文时，请在中文与英文、中文与数字、英文与数字之间增加空格。例如：正确： Github 于 2007 年 10 月 19 日正式上线。错误： Github于2007年10月19日正式上线。一段文字中有超链接的部分，在超链接的前后使用空格。例如：正确：你可以前往 Linux 开源仓库了解详情。错误：你可以前往Linux 开源仓库了解详情。英文、数字前后接「中文全角标点符号」或「表示单位的角标符号」时，不需要加空格。例如：正确：新 MacBook Pro 有 15% 的 CPU 性能提升。错误：新 MacBook Pro 有 15 % 的 CPU 性能提升。正确：我家的光纤入户宽带有 10Gbps，SSD 一共有 10TB。错误：我家的光纤入户宽带有 10 Gbps ， SSD 一共有 20 TB 。

对于有特殊用法的专有名词，如 4K、1080p、iOS 13 等，英文和数字之间是否空格以官方标准为准。

每段文字的开头不需要空两格（不需要首行缩进）。

# 2.2 标点符号中文内容引号请使用直角引号「」，而不是弯引号“”。推荐：「同学，『GitHub』的『GitHub Actions』服务免费额度是多少？」不推荐：「同学，“GitHub”的“GitHub Actions”服务免费额度是多少？」

注意，这一点并无对错，只是推荐与否。实际上，如果所在内容平台的全角弯引号比较美观的话，还是可以使用的。但是知乎的全角弯引号很丑，就不要在知乎用全角弯引号了。

省略号请使用「…… 」标准用法，正确输入方法是切到中文输入法然后按住shift + 6。不要使用三个句号「。。。」，也不要使用三个英文句点「...」。正确：更多新的技术也随之孕育而生…… 错误：更多新的技术也随之孕育而生。。。错误：更多新的技术也随之孕育而生... 不要重复使用标点符号，尤其是在表达强烈情感的时候。例如：推荐：这个提议真棒！我喜欢。不推荐：这个提议真棒！！！我喜欢~~~~ # 2.3 中文和西文符号一般情况下，一个中文句子中出现了英文部分，仍然使用中文标点，即全角符号。例如：正确：我常用的电子设备是 Kindle、iPad Pro、iPhone。错误：我常用的电子设备是 Kindle, iPad Pro, iPhone. 正确：核磁共振成像（NMRI）是什么原理都不知道？JFGI！错误：核磁共振成像 (NMRI) 是什么原理都不知道? JFGI! 如果引用一段完整的英文句子，或是出现在专有名词中的标点，则不需要更改标点符号。例如：正确：乔布斯说「Stay hungry, Stay foolish.」错误：乔布斯说「Stay hungry，Stay foolish。」正确：我最喜欢的手机游戏是《Lifeline: Silent Night》。错误：我最喜欢的手机游戏是《Lifeline：Silent Night》。 # 2.4 专有名词专有名词使用正确的大小写。例如：正确：使用 GitHub 登录错误：使用 github 登录错误：使用 GITHUB 登录错误：使用 Github 登录正确：我们的客户有 GitHub、Foursquare、Microsoft Corporation、Google、Facebook, Inc.。错误：我们的客户有 github、foursquare、microsoft corporation、google、facebook, inc.。不要使用不地道的缩写。例如：正确：我们需要一位熟悉 JavaScript、HTML5，至少理解一种框架（如 Backbone.js、AngularJS、React 等）的前端开发者。错误：我们需要一位熟悉 JS、H5，至少理解一种框架（如 backbone、angular、RJS 等）的 FED。对不常见的缩写进行介绍。例如：推荐： OCR（Optical Character Recognition，光学字符识别）不推荐： OCR（光学字符识别，Optical Character Recognition）错误： OCR (Optical Character Recognition, 光学字符识别) # 2.5 文字样式

文字样式的使用可以增加文章的可读性，但是过度使用则会造成排版混乱，因此建议大家正确、克制地为文字添加样式。

例如，需要着重显示的部分请使用「加粗」功能，而不要使用「斜体」，更不要使用「加粗 + 斜体」的组合。

注明引用来源

文中有使用外站或外部内容的，务必在引用最后部分注明来源。若文章为全文翻译，必须在文中注明原作者及原文地址，并添加原文链接。 # 3. 选题系统化 # 3.1 主题分类

主题分类因人而异，但是你必须形成自己的主题分类系统，这样才能作为一个起点帮助你发现写作灵感。下面给出了一套主题分类作为例子。

1. 技术细节型

频率：每周 1~2次，15~30 分钟可以写完。

《一文搞懂取余和取模的区别》《如何禁用 Homebrew 每次安装软件前的自动更新？》《DHCP Offer 报文为什么可以单播发送？》这种主题类型主要来自于日常工作，但是好像写这一类的人不多。每天我们都会遇到不同的技术问题：如某个第三库更新，某个浏览器 bug，类似于面试八股文一样的某个技术细节问题。当然，也并非所有的技术细节都值得我们大书特书，我们应该判断问题的价值以及我们是否有可能后续还会遇到这个问题。

取名建议

其实这种类型更像是我们平常遇到问题会在 Google 中搜索的内容，如果你也擅长用Google的话，我想你就懂了奥秘。标题的前半部分是关键字，后半部分指名意图。

2. 干货型

频率：每月 1~2 次，1~2 小时可以搞定。

《后端工程师不容错过的 10 个一站式前端模板》《20 个冷门好用的 Linux 命令》《使用 InfluxDB 和 Telegraf 为服务器搭建酷炫基础监控》

通常来说，这一类型的文章都是作者一段时间对于某一个东西的总结，非常有收藏价值。

故而，这种类型的文章会在 GitHub 或者聚合网站上比较受欢迎。所以，它也更容易传播。但是写起来的难度比较大，这依赖于你的使用经验。所以，也不是一天、两天就能搞定的。我个人认为这类文章不过分强调技术，只是我们对某个或某类技术工具的使用心得。

取名建议

有一点标题党的感觉。

3. 实践总结型

频率：每月 1～2 次，2+ 小时以上的时间。

《Linux 内核剖析（一）—— BIOS加载内核》《Dubbo：从入门到放弃》《编辑 - 发布 - 开发分离：Git 作为 NoSQL 数据库》

这有可能是一系列的文章，而这一系列的文章一般是连续写出来的。因此，我们可以发现很大的书都是由这一类的文章衍生出来的。

这一类的文章更像是干货型和技术细节型的结合，面向特定领域的技术，也属于干货。对于这种类型的文章来说，更依赖于代码——读者需要依据代码一步步往下深入。所以在这一类型的文章中代码往往比较重要。

取名建议

听起来就很掉头发，需要很多时间来完成博文。（“干货型”虽然也需要时间，但这个时间是来自于我们日常工作的积累，可能写对应的博我只需要很短的时间）

4. 杂谈与鸡汤型

频率：每季度 1~2 次，少则几小时，动则上月。

《为什么整个互联网行业都缺前端工程师？》《成为字节跳动 CTO 是怎样一种体验？》《程序调试必须使用调试工具吗？》

简单地来说这一类文章基本上是没有技术的，都是一些以理论为主的概括。同时，写这一类文章的时候，也意料着可能在某一领域有一定的水平，写出来才会有人看。

取名建议

提问语句为主，引发思考。

# 3.2 风格内容

为了能让读者能够直观地理解你的观点，逻辑清晰、语句通顺是必须要做到的。同时，为了增加文章可读性，提出以下几点建议：

理清文章结构，动笔之前可以先列一下写作大纲。用主动语态，不要用被动语态。一般情况下，主动语态比被动语态更有力。使用具体、明确、展示细节的词汇，能激发想象，使读者自己代入情境。「把硬币放进口袋里，他咧开嘴笑了」，远远强过「他满意地拿走了辛苦挣来的奖赏」。减少形容词的使用，少用「的」。文中涉及到参数规格、数据的部分，要保证严谨性。文章完成之后通读一遍，记住，不要让读者猜测你在讲什么。试着去表达一些技术上的细节，也会省去一些技术上的细节。记得在文章开始配上 README 性质的引言。技术文档并非一次性写作，我们需要后续不断对历史文章进行校正、丰富、优化。 # 4. 维护简单化

我的技术文档的技术选型是：

使用 Hexo 进行技术文档内容原信息的 META 管理、编译生成博客页面；使用 NexT 这一经典、稳定的技术文档主题；使用飞书文档来编技术文档内容，点击技术文档

文章标题会跳转到对应的飞书文档。

实现这一方案需要对 Hexo 和 NexT 的源代码做一点小改动，我准备了一个开源仓库包含了这些改动。

# 5. 参考资料少数派写作排版指南 - 少数派 (opens new window) 中文文案排版指北 (opens new window) 程序员怎样才能写出一篇好的博客或者技术文章? - 知乎 (opens new window) Hexo-NexT-Index - 使用飞书享受博客写作乐趣 (opens new window)

【本文地址】

公司简介

联系我们