为什么几乎所有技术文档读起来都非常难受?

更新日期: 2022-09-05阅读: 225标签: 文档

我们学习一个新接触的文档时,常常觉得非常难受,而自己消化了再写教程就非常舒服,这会让人产生一种错觉,就是官方文档没好好写。

那么实际上,官方文档为什么长期以来,难以代替第三方教程的存在呢?

在开源了一系列程序后,除了能力和意愿问题外,我发现这个过程中有几个非常大的影响因素,不亲自从事很难意识到,这里分享一下。

(一)学习者视角

初学者看似啥都不懂,但其实是有一个光环的,就是我看不懂就是顺序错了。而懂了的人如果不是借力求学心路历程,或者在大量教学中迭代,是非常难做出详略得当、顺序合理的阅读材料的。

不幸的是,作者刚好是受知识诅咒最深的人。因为读者一上来看到的就是完整品,会有一个自然发生的概括性认知;但实际上开发它的作者,在心中早已经酝酿过了无数种可能,时间上也旷日持久,早已经难以回忆起这种状态了,一上来无从说起才是常态。

创作者潜意识中的“常识”,也往往与学习者有很大的差别,因为这正是创作者能无中生有一个作品的原因。从学习者的角度,很容易描述它和以往所有软件的差异点(如果这是一个好软件),但对创作者来说,却并不是这样,因为他们心中有一个整体性的“事情应该的样子”,它是一个整体,就是单纯觉得现有的工具哪儿都别扭,而学习者或者宣传者所说的“本质”,其实从某种意义上讲只是“差异点”,只是由于这个差异点本来想不到,现在见识到了,所以印象非常深刻。

(二)功能更新

说白了,一个好的教程的核心,就是一个新接触者循序渐进展开使用的心路视角。

但是程序总会迭代,不论第一版做得多自洽,有一些看似细节功能的引入,总是会润物细无声地慢慢催生出完全并行的不同的使用逻辑和组织思路。

这种情况下写文档会非常难受,因为新功能会让旧功能莫名其妙没有用武之地,而不了解旧功能又难以理解新功能究竟为何会长成这样。这不是增加几句文档能解决的问题,它需要整体大改、重新写才有可能改善(类似于程序层面的重构),而这个成本非常大。

本质上,这其实是程序工程本身的微失控,在文档层面的一个反映。

(三)翻译时的语言障碍

我对翻译腔是比较敏感和反感的。直到有一次,我自己的文档,先写了英文,后写中文,然后我才发现,哪怕是母语,哪怕是原作者自己最知道自己要说啥,在先写了另一种语言的情况下,都会受到强烈干扰,而有种不会讲话了的感觉。

换言之,翻译的文档不好可能不仅仅是因为具体的语言障碍,导致翻译者难以明白原文意思,或要翻译成的语言使用上不地道,而是说不同语言之间本身就有障碍,原作者在频繁更新软件、更新测试并更新文档时,还同步更新翻译的话,语境不知道要切换多少次,其实是非常沉重的负荷。其难度差异类似于,作为程序员改两个bug,和身兼程序员与销售、改bug与接待客户交替进行之间的差别。

小结:

以上原因都可能造成原作者哪怕有心又有力,效果却依然比不上第三方出手。

希望我的分享能对即将做这件事的人有所帮助,提前有所准备,或发生后减少困惑的时间。

也希望能有更多人参与到这件事里来,因为不管你是什么身份,当你觉得奇怪为什么不做得更好明明很容易时,很可能天时地利人和恰巧你就是最适合干这件事的那个人。

原文 https://zhuanlan.zhihu.com/p/561296095

链接: https://www.fly63.com/article/detial/12088

docsify - 生成文档网站简单使用教程

docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件,所有转换工作都是在运行时进行。

DTD文档模型是什么?

DTD文档模型是DOCTYPE文档声明,是Doucument Type Definition的英文缩写,是文档类型定义;制作一个标准的页面,声明一个正确的DOCTPYE,HTML里面的标识和CSS才能正常生效.

撰写后台需求文档需要注意的那些事儿

很多产品经理在撰写后台的需求文档时会一脸懵,很多时候不知道怎么开始,这篇文章主要根据自己工作中对后台的理解和需求文档撰写经验进行分享。人员较小的公司,会要求产品经理后台管理和前台界面一起进行撰写。

什么是<!DOCTYPE html>,以及其重要性

在HTML文档初,往往会有这么一句话<!DOCTYPE html>,那么它的意义是什么呢?它是html5标准网页声明,全称为Document Type HyperText Mark-up Language,意思为文档种类为超文本标记性语言或超文本链接标示语言,现在是这个简洁形式

docsify一个神奇的文档生成工具

在开发项目时,我们或许需要一份精致的开发文档,那么使用docsify是不错的选择,docsify是一个文档生成工具,它直接加载 Markdown 文件并动态渲染,同时还可以生成封面页。所以我们只需要写完 Markdown 文

程序员为什么不写文档?

为什么程序员不写文档?是不想写吗?最近,资深软件工程师 Kislay Verma 分析了背后的深层原因。他认为软件工程师不写文档有以下两个主要原因。

React新文档:不要滥用Ref哦~

React新文档有个很有意思的细节:useRef、useEffect这两个API的介绍,在文档中所在的章节叫Escape Hatches(逃生舱)。显然,正常航行时是不需要逃生舱的,只有在遇到危险时会用到。

程序员应该写文档吗?

80% 的文档都是无效的,所以多数情况下,程序员都不用写文档,原因如下:多数文档都是代码的点缀或者静态的记录已经实现的代码,懂代码的开发人员会直接看代码,不懂代码的开发人员压根不会看。

内容以共享、参考、研究为目的,不存在任何商业目的。其版权属原作者所有,如有侵权或违规,请与小编联系!情况属实本人将予以删除!