技术文档如何编写?

关于文档编写的几个思维

近期重新组织了好几篇技术文档,把其中的一些感悟提炼出来。

文档为达到容易理解和操作的程度,对大量的语言重新组织,内容的不同呈现,借助辅助工具等一系列操作,本文就是剖析整个流程

全文主要的流程是:

  • 编写文档前,准备工作有哪些?
  • 根据现有文档的问题是?
  • 语言的组织和内容的不同呈现方式有哪些?
  • 按照现有文档完成后的文档输出如何组织?

0. 程序员如何看待文档?

程序员一定会是接触各种各样的技术文档,文档写的好与不好,大致都能区分出来。

但是对于自己写的文档却可以容忍 “丑陋” 、“难以理解”等......

对技术、代码可以修改、修改、再修改,优化、优化、再优化......

我觉得出现问题在于:程序员对于如何有效的逻辑表达以及优秀的排版没有意识。

据我观察,一个程序员完成了一份代码的编写,对文档只会花小部分时间进行书写,会自然而然的忽略部分信息,认为把信息堆砌出去,就是一篇文档......

不不不,我认为不应该这样......

但凡伟大的公司、产品对“呈现” 这一块都绝对的重视。尽量都在简化用户的操作复杂程度,比如极度克制的微信。

1. 什么是好的文档?

如何定义一份文档是通俗意义上的好?

就个人的认识,可以从 GitHub 上的最热门的开源项目的文档入手?

比如个人最崇拜的世界 Python 技术排名第五的作者: kennethreitz,他的开源作品:requests

再比如:开源 web 框架 Django

这两个项目的文档堪称是教科书式文档示例。

阅读这些项目的文档,一定有个感官的认识:文档写的好,根据文档能使用起来,整体文档的风格也高度的统一。

一个好的文档我认为具有下面三个特点:准确、清晰和美观

准确和清晰对应逻辑梳理和表达。 美观对应排版。

pic_1.png

2. 编写文档的整体流程有哪些?

我现在的步骤是:

  • 收集
  • 梳理
  • 实践
  • 编写

2.1 收集

  • 根据 wiki 收集现有的资料,以及相关故障的问题记录文档(其中已知的故障问题文档很重要,这能让你明白别人问题会出现在哪)
  • 和原文档编写者沟通(也能让你感性的认识到他口中的文档的问题)

2.2 梳理

  • 根据收集的到的资料,感性的认识到文档的整体流程是什么,以及需要注意些什么
  • 记录:把已知问题进行记录

梳理环节主要是关注现有文档的整体流程以及你如何可以对现有流程优化

2.3 实践

  • 根据收集的资料和现有的文档进行操作
  • 注意你的出错的点,以及你根据别人的提示避开的出错的点

实践环节主要是关注那些 ‘坑’,直到你成功的按照步骤得到理想的结果

2.4 编写

现在手头你已经有历史经验(收集的资料)和 实践经验(实践环节)。

进行文档的编写需要注意两个点:

  • 逻辑表达、内容组织
  • 排版

一篇文档主要包含这些内容:

  • 标题
  • 文本
  • 段落
  • 图片
  • 表格

pic_2.png

这里有一篇中文技术文档写作规范参考:阮一峰:中文技术文档写作规范

标题:

我只谈论一点:标题原则上存在六级,即一级、二级、三级、四级、五级和六级标题。但我推荐使用前三级标题,其余的使用列表项目进行组织。因为层级组织多了,其实是并不太友好。

文本:

参考示例中讲了很多,我值谈论三点:

  • 重点强调使用加粗处理,且重点强调的不应过长。比如你强调了几百个字符,其实相当于没起到强调的作用
  • 注意中英文的处理:即英文和中文强化空一格。比如:English 英语
  • 慎用斜体

段落:

我谈论一点:

  • 各段落中间使用换行处理。
  • 一个段落不应过长,尝试拆分成几个段落。

图片:

我谈论两点:

  • 图片的作用:即对一些文字不好描述的使用图片视觉化呈现
  • 图片的大小:文档内的图片建议大小一致:即宽度和网页同宽度;达不到需求的建议居中处理。

表格:

我谈论一点:

  • 表格的作用:对内容的分类和组织,能用表格表达比文字好。

其他:注意整体风格。

综上:编写文档的两个思维是:

  • 流程化:1. 先有什么 2. 后有什么 3. 最后结果
  • 精细化:逻辑表达、内容组织、排版

pic_3.png

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏iOSDevLog

ARKit

一个增强现实(AR)描述了用户体验,从设备的摄像头的方式,使这些元素似乎居住在现实世界中添加2D或3D元素到实时取景。ARKit结合了设备运动跟踪,摄像机场景捕...

1192
来自专栏吉浦迅科技

推荐5种让数据库快的飞起的GPU加速产品

GPU承诺会彻底改变大数据分析领域,从当前来看,这并不是虚言,当我们数据量达到一定级别的时候,我们一定会转向使用GPU。大多数的数学密集型应用都包含机器学习框架...

4739
来自专栏逸鹏说道

大公司都有哪些开源项目之百度

百度分享的一些开源项目偏前端。https://github.com/fex-team/ ? 1.UEditor 编辑器 UEditor是由百度web前端研发部开...

3036
来自专栏数据派THU

独家 | 手把手教你学习R语言(附资源链接)

作者:NSS 翻译:杨金鸿 术语校对:韩海畴 全文校对:林亦霖 本文约3000字,建议阅读7分钟。 本文为带大家了解R语言以及分段式的步骤教程! 人们学习R语言...

2857
来自专栏BestSDK

OpenAI 开源机器人模拟 Python 库:优化API接口提升400%处理速度

在OpenAI的许多项目中都使用域随机化技术。 最新版本的mujoco-py支持支持自动的(headless)GPU 渲染,与基于CPU的渲染相比,它的速度有4...

40111
来自专栏CDA数据分析师

这4件事带你走出深陷的数据分析迷宫

通过真实世界中的实例,我们将共同通过种种错误的数据分析方式总结出正确的技巧与诀窍。 相信每位朋友都遇到过这样的情况:将来自各类渠道的数据收集起来,通过A/B测试...

2106
来自专栏phodal

如何为技术博客设计一个推荐系统(中):基于 Google 搜索的半自动推荐

与统计学相比,基于内容来向用户推荐相似的内容,往往更容易获得。对于推荐来说,则有两种方式: 手动推荐 自动推荐 (PS:我承认,这句话说了等于没说。) 如下图所...

2466
来自专栏小狼的世界

BLOG首页展示的几种方式

大约在多年以前,按照日志的时间格式进行排列的类似于编年史样的风格非常流行,但是最近,摘要形式的首页展示开始变得流行起来,还有一些其他的展现形式,我们的Blogg...

691
来自专栏大数据杂谈

Python爬取自己微信好友信息,并制作好友签名词云

本文参考教程来自微信公众号【Alfred在纽西兰】,文章如下: 《一件有趣的事: 爬了爬自己的微信朋友》 根据原作者的思路以及代码,爬取自己的微信好友信息并制...

3175
来自专栏Petrichor的专栏

如何画 软件工程 流程图

个人推荐一款常用的免费在线绘图工具:ProcessOn 。之前也看过比较过其他的 流程图绘图工具 ,要么是功能不够强大,要么就是伸手向咱学生党要钱,或者只给个短...

2433

扫码关注云+社区

领取腾讯云代金券