专栏首页GopherCoder技术文档如何编写?

技术文档如何编写?

关于文档编写的几个思维

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

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

全文主要的流程是:

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

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 条评论
登录 后参与评论

相关文章

  • ReStructuredText 文档编写全攻略编写文档说明

    谢伟
  • 『No17: gin-swagger 构建自动化文档』

    重要,前后端的交互一般流程是这样的,后端暴露出API后,交给前端,前端根据API的响应,编写前端页面,一定程度上API 是前后端的交互桥梁。

    谢伟
  • kafka 上手指南:集群版

    在消息系统中,涉及的概念都比较类似,初学消息系统,概念有时候理解不到位,需要读者反复的根据自己的学习进度回过头把基本概念捋清楚。

    谢伟
  • 总监突然把我拉进了一个群……

    大噶好,又是我,TAPD的产品经理圆圆。 上周一上班的时候, 我发现隔壁组来了个巨帅的小哥哥。 ? 有多帅呢?可以说,是吴彦祖+金城武的那种帅。 我立马就去企...

    TAPD敏捷研发
  • 谷歌软件工程师是怎样写设计文档的?

    谷歌软件工程文化的主要元素之一就是通过设计文档定义软件设计。在开始项目编码工作之前,软件系统或应用程序的作者会创建这些相对非正式的文档。设计文档记录了高级实现策...

    深度学习与Python
  • 程序员既要写好代码,又要写好文档

    程序员既要写好代码,又要写好文档 作为一个长期混迹于CSDN社区的人,我对很多拥有高访问量的博主钦佩不已,特别是在参加了CSDN在举办“2014 CSDN博文大...

    用户1289394
  • 读不懂英文文档,能写出代码不?

    作为一个开发人员,开发一个新项目,维护一个项目,想要快速的开展工作。最重要的是干什么?是阅读项目文档,没文档看代码。可见我们首要做的事情是看文档看懂文档,编程初...

    程序员互动联盟
  • DAS 2020 Keynote Speech | Adobe 文档分析技术介绍

    DAS 2020 (Document Analysis System,文档分析系统研讨会) 于 7月26-29日在武汉召开,本次研讨会中有不少精彩的内容,昨天向...

    CV君
  • GO 文档笔记

    最开始写 GO 的时候, 发现方法的注释并不支持@param, @return等参数, 搞得我都不知道该如何给自己的方法写文档说明了. 而且网上搜了搜也没有搜到...

    烟草的香味
  • 文档!文档!文档!重要的事情说三遍!

    项目一期基本开发完毕,包括后台管理系统以及提供给手机端的接口还有SSO,由于奔着敏捷开发去的,文档没有过多花时间去写, 当然了文档肯定有,开发人员写的自己能看懂...

    风间影月

扫码关注云+社区

领取腾讯云代金券