为什么有些文档的作者这么人上人

[MaMimi]

我承认他们费心费力维护文档用爱发电, 但是这个语气为什么一定要这样, 有种小学 6 年级学生和 1 年级学生讲话时的内心戏的感觉

没有谁否认这是一份写的详细, 容易读懂的文档, 只是觉得作者有些东西没有必要一而再的强调

有些老哥可能误会了我因为配置失败, 把自己代入到作者所说的“鉴于目标读者的水平”, 毕竟能上 v2 配置个 gradle 代理也不是什么难事. 实际上我想表达的是#38 @acmore 所说的: “都做了那么多了，何必在这里选一个有可能不招人喜欢的说法呢。”, 标题的用语过激是我的错, 我还是很感谢作者写的文档.

[zoharSoul]

因为小白太多了

[cairnechen]

说实话，我感觉这算客气的了

[kera0a]

有没有可能他只是实话实说呢

[Issacx]

我觉得还挺贴心。不需要的不看就是。

[fgwmlhdkkkw]

mc 的启动器吗？

[Leonard]

其实还好了，把用户（这里指读文档的人）当成小白是比较保险的做法。因为受众水平本来就参差不齐，你觉得不需要的略过就行了。

[cmdOptionKana]

有一个关键点：他们的主要读者是些什么人，会不会真的以小白为主呢？

[dqzcwxb]

他说的不挺好的吗
写详细点被骂,写笼统也要被骂,那下次他不写了你来写?

[memedahui]

文档写的非常棒,就连会发生的错误也写,我觉得完全没问题.

[yuhangch]

求个楼主头像来源

[heyjei]

目标读者清晰，赞！

[wolfie]

看不懂点这里 ❌❌
菜逼点这里 ✔✔

[coderluan]

这种情况确实不好，骂的人其实并没有完全得到发泄或者彻底避免问题，路人还会感觉作者态度不好，所以我有了个突发奇想：

可以弄个新的开源协议，简称 FYL ，全称大家懂的，该协议和主流协议兼容，主要就是额外规定，你要是打算使用这个开源代码，就要忍受作者的脏话和侮辱，包括不限于代码文档和注释，当然你可以选择不用，用了就不要抱怨作者的态度不好，抱怨只能说明你没做好使用该协议的思想准备。

[vanton]

按照我的经验，这个已经很客气了。
很多用户会提出一些完全不知所云的 issues ，你要回复就是浪费大家的时间。

[vanton]

不过这个文档有些错误，比如“介于”应该是“鉴于”

[MaMimi]

@cairnechen 那还是我看的太少了

[Kinnice]

# 小白教程
1.xxxx,xxxxxx
2.yyyy （ xxxx 链接）

# 老手教程
自行理解，不懂直接啃代码，若没有代码自行反编译理解

[MaMimi]

@kera0a 我怀疑你在说我, 但是我没有证据

[Shura]

楼主是配置失败了，然后感觉被作者侮辱了吗？

[cmdOptionKana]

@coderluan 然后就会有人发帖问：我承认这个项目的作者辛苦了作出了贡献，但他为什么要采用这种充满内心戏的中二病协议？

[MaMimi]

@dqzcwxb 只是觉得没必要一再强调目标读者是小白, 想要详细就详细, 粗略直接粗略就行了, 我一开始也说了维护这种文档是吃力不讨好的事情用爱发电

[MaMimi]

@yuhangch 阿里开源图标站的

[MaMimi]

@Shura 我气急败坏了属于是

[MaMimi]

@fgwmlhdkkkw forge mod 开发文档

[AyaFrost]

有必要的话，感觉最顶 /底下强调下一次鉴于读者水平，所以 XXX 就差不多了
文内多次说读者水平怎么怎么样的话，确实不太舒服

[EPr2hh6LADQWqRVH]

又当又立，边割边骂，这种人不光 Java 有，前端更多

[eason1874]

我写文档也喜欢建议小白用户这样那样做，有的问题问烦了我会连该按哪个按键都专门写出来

当然我不会说鉴于目标读者的水平，我会说这部分内容写给小白，老用户可以跳过

[zxcslove]

可能是担心使用这玩意的人太多吧

[knightdf]

可能他已经被别人问烦了

[Phishion]

如果这个能让你感到被冒犯，那可能是你个人的原因，我觉得其实还好啦，一般气急败坏的都是配置失败的人吧，这样别人也算实话实说了，你要虚心接受。

[cmdOptionKana]

@AyaFrost
@eason1874 我猜这个写文档的人本来也是想写 “这部分专门写给小白看，老用户可以跳过”，只是这个措辞怎么说怎么容易得罪敏感的人，不写清楚吧，又怕被误认为全是必要操作。

想来想去，好像没有绝对安全不被骂的表达方式。

[advancejar]

当年学软件工程的时候老师说：写说明文档要把用户当白痴。
我觉得他实践的很好。

[blockmin]

以前开车的时候发现人真是不一样的
你以为只要吧东西放那了，想要的去拿就好了。然而不是，需要给到手里。给到手里后以为就完了，然而还不是，还需要人喂。喂到嘴里以为没事了，然而 tm 还不是，你得帮他嚼碎了喂。还有奇葩要你帮他咽。
现在我一律认为，还不会那就是不配，自己花钱找别人帮忙喂吧

[deplivesb]

难道不是么，说句实话就被你说成人上人？

[Huozy]

建议给他提个 request 怼回去

[MaMimi]

@deplivesb 我用词过激了, 其实并没有那么大的恶意和批判

[Biwood]

其实还好，至少用了很多“请”字，只是最后一句可能让一些人感到冒犯，取决于你用什么语气去读了，“人上人”的说法有点夸张

[acmore]

也不能说是人上人，臭写代码的有一个算一个哪有人上人（狗头
不过情商不高是真的，有些事就是有不同的说法，要么写长文发泄怨气，要么就从一而终当个好人。都做了那么多了，何必在这里选一个有可能不招人喜欢的说法呢。
这差不多相当于乐善好施地做好了几大锅粥，然后摆在庙前大喊 “介（鉴）于秃子不种地，赶快来吃粥罢” 么

[FrankFang128]

说事实也不行吗

[tankb52]

我曾经分享一个 markdown 转 PDF 的文档给同事。大致有以下内容：
1. 将以下命令复制后在 CMD 窗口执行
2. 打开 CMD 窗口的方法：XXXX
3. 命令本身——因为是 markdown 中的代码格式，所以有一个引用框的效果。

然后邮件发给旁边的同事看。
我就眼睁睁的看着他用鼠标指着文本一行一行的读，读到第一行后就问我：“唉下面的命令呢？”然后马上又自己回答：“哦在下面我看到了。”

当然也见过有的人，给他关键字让他百度，他发个截图给我看说百度了也没有，其实截图中第一个结果就给出了正确回答的。

所以对你的读者不要报有任何的期望。
语气确实有点不温柔。但我能理解。

[lucybenz]

1 、如果按照文档部署不起来 出错 那就是文档的原因；
2 、这么阴阳怪气的写文档，确实自持优越感；
3 、搞个同类产品 做出更严谨优质的文档干掉他

[efaun]

是有点阴阳怪气了

[MaMimi]

@acmore "都做了那么多了，何必在这里选一个有可能不招人喜欢的说法呢。" 这确实是我最想表达的意思

[yohole]

我觉得要知道作者经历了什么再来评价也不迟，唯心地认为，这文档的描述问题不大，做技术的有点个性无伤大雅的，不是任何事都上纲上线，你看 Linus 在语言上的争议还少么？

[tutu10]

@acmore 有被这个比喻笑到

[GalaxyVIP]

感觉挺正常的啊，也没有不尊重谁吧。说明这个文档的目标读者确实是小白啊，作者也就是多提供了几个途径，免得动不动就伸手党很烦的。

[pC0oc4EbCSsJUy4W]

一而再再而三的给人喂饭,你体验过就不会这样说了

[Mogugugugu]

Forge 的群体有小学生的。。。或者说很大一部分可能都不知道什么是 Java 的 = =

[YaakovZiv]

可能是作者被问一些基础环境问题感到烦了吧，即便给出基础环境需求的组件，还是会有人问基础环境要怎么处理。
题外话：我就遇到过那种让我很难受的同事，同事是五年经验的.net 开发，看文档有三个月了，突然问我一句，文档开头说的 ssh 云主机是啥，我就感到很心累。真想劝他转行。但凡有两年经验的开发，自己查资料的能力得是有的，这个要求不算过分。

[yidinghe]

就是作者内心戏多点而已

[RiceNoodle]

我觉得你的直觉没错，写详细点，和语气没关系，文档没必要这么写的。

[sky96111]

有可能…这个 mod 的大部分受众用户确实在这个水平呢？ mc 这种老少皆宜的游戏玩家年龄跨度很大，甚至可能还在读小学

[cmdOptionKana]

@acmore
@MaMimi

"都做了那么多了，何必在这里选一个有可能不招人喜欢的说法呢。"

我觉得有两个问题：

1. 可能作者只是想到什么就写什么，而不是故意选择一个不招人喜欢的说法。因为每个人的敏感度不同，前面很多楼都说不觉得语气不妥，也许作者恰好也是对语气不敏感的人。

2. 假设作者是故意选择这个说法，也问题不大，因为“做一个彻头彻尾的好人形象”是一种选择，“做一半好人，一般有刺的人”也是一种选择，很难说哪个是更好的选择吧？人有不同的性格。

[kett]

还好吧，毕竟不收费，又有用。

[Latin]

提问的智慧

[c6h6benzene]

写文档不就该当用户什么都不懂来写吗…都懂的话为什么会来打开这份文档？

[lingyan190]

鉴于用户可能在实践中出现各类问题，作者并不方便一一解答，建议使用推荐配置或者离线包。
这样写不好吗？？？为什么非要预想一下水平，再说 git 上面给加星可是能反馈到简历上的，稍微对小白友善点怎么了吗

[lostberryzz]

上个网怎么这么玻璃心呢，不想看关掉就行了，另外 mc 的玩家还真以中小学生为主，文档的作者应该是实话实说，说实话如果我完全不懂技术，看到作者这段话，我只能感觉到很贴心，很为小白考虑。

[sgissb1]

两个原因，因为伸手党太多了，出了问题就是有一定的懒惰思想，总想着别人帮他解决掉，或者最好包圆了。
另一个是“大佬”不在少数，说话做事很多时候只考虑自己的“立场或地位”。

反正看看就好，无所谓的事情了。

[laydown]

这就受不了还是怎么的？我觉得语气没什么问题啊，这么贴心了还得怎么样呢？不是很理解。如果楼主来改写，会怎么写呢？

[hyy1995]

不知道楼主是不是入行不久哈……


我就 4 年研发经验，说久也不久，但深感程序员这个行业的下限有多低，不会思考的伸手党、工作几年技术菜到你想象不到的人，真的太多太多了。做开源的一定“深受其害”，这种语气接地气，我觉得一点毛病也没有，比起某些企业的 KPI 项目充满一堆自造词语、让人一头雾水，要强很多

[ByZHkc3]

为啥我觉得很贴心？你要是做过项目答疑的话，就知道用户是有多傻逼了。

[wccc]

可以尝试做一下开源

[learningman]

When computer sciense expert write 'user', they mean idiots.

[alexkkaa]

作者的行文确实让人觉得有点刚， 不过我相信它的目标阅读者不会有任何不适

[a154312237]

我觉得挺搞笑的
作者为小白考虑已经非常 nice 了
作为小白有些文档看的一头雾水 很多时候请教下作者能收到回复的也不多

[a154312237]

⬆️搞笑指文档作者措辞有幽默感 褒义

[Tyuans]

可能你没有遇到那种连解压都不会的人来问。

[xdeng]

你是站在你懂的方式看，很多小白还是很感激这种提示的。

[yaoyao1128]

因为不懂的人太多了啊……
并且还有各种不懂就写 issue 的

[Felldeadbird]

楼主试下写一款工具，当你接触到一定群体，你就会觉得这份文档说明是完全没有一点毛病。

[Cielsky]

我感觉已经很客气了。
可能是被小白问烦了吧。
毕竟很多小白用你的东西还觉得他是大爷你得伺候着

[tomczhen]

付费了没？捐助了没？贡献了没？
要是都没，这个项目对我有用，我觉得作者跟我比起来确实是人上人。

[ncepuzs]

下次请连带链接（ https://boson.v2mcdev.com/devenvironment/setup.html ）一起提供，不然别人怎么判断作者说的对不对。就这里，我觉得作者这么说没什么大问题。

[Aixtuz]

看看交通法规的内容？你会发现那里面强调的内容更过分。
为啥会强调呢？因为总结这些经验所付出的代价太沉重。

[rpman]

我第一次装 forge 的时候应该还是个中学生

[Jooooooooo]

你被 100 个装了 jdk 7 的人追着问了好几个月也会这么写的.

[huntagain2008]

我作为小白很喜欢这种注意事项很详细的文档。某开源 BBS 的文档开篇讲安装，使用方法没有，最后用“爱用不用”作为结束语给我一种开源大佬很霸气的感觉还有“这项目真能用吗”的疑问。

[kuangwinnie]

如果是 mc 启动器的文档，你要知道用这个包，试图安装这个包，甚至试图开发这个包的朋友；

可能字面意义上，真的是未成年的小朋友。

[GeruzoniAnsasu]

因为这个文档真的会有 6 年级小学生来看




我也会这么写。

[M2K4]

很符合程序员给人的刻板印象

[documentzhangx66]

我当年本科大一时，带了一些研究生，因为我很小就被几个大佬带着学 IT ，导致我觉得这些研究生贼菜，然后我经常骂人.....直到后来我不懂感情学，被渣女完虐，才开始老老实实向感情学大佬学习，才慢慢理解菜鸟们的感受。

我觉得，写教程，就专心写教程，如果你要考虑读者的水平，做区别化处理，你完全可以好好讨论：入门者请点这里补充一些知识，大佬请跳过啥的。直接在文档里开骂，或阴阳怪气，不是大佬风范。

另外，林子大了，有些人喜欢出来捣乱，在所难免。这个论坛里，我经常会遇到某些人，他们一上来，不会指出你写的东西，具体哪里不对，他们只是发泄情绪，说你写的不对。如果你认真地问他们，哪里写的不对，他们又指不出来，然后继续阴阳怪气。其实这类人，无视就好了。

我在论坛里写东西，主要原因是希望和真正热爱 IT 的人进行交流，同时也能得到一些大佬的指点，比如：

@chenyu8674 帮助我找到我找了很久也没找到的单机 wow.
@msg7086 给了我一个大容量硬盘进行连续 IO 的数据，我曾经一直错误以为大容量硬盘做一次全盘检查需要很长时间，最后在这位大佬的指点下，我发现是自己设备有 IO 瓶颈，等等...

总之，林子大了，啥人都有，习惯就好。取其精华。当你觉得有问题，就认真问一下对方，但当对方只是来撕逼时，你就不要浪费时间了。

[msg7086]

@documentzhangx66 谢邀，很高兴能帮到你。

正好进到主题了就说两句。
有些东西会变成什么样子，是有他的道理的。你没有站在他的角度，没有经历过人家可能经历过的悲惨经历，你大概率不知道他为什么会这么写、这么说、这么做。

比如说我们字幕组招新。
以前都是考官直接和新人去对接，考察水平然后决定是否通过。
考官自己也要上班，都是下班时间边做片边面试新人。
但经常会遇到一些自负但很菜的新人，觉得自己老牛逼了，被我们刷下去以后就恶语相向。见过追在后面一直问的，见过发邮件发私信质疑的，最强的一个应该是被我们因为一个低级错误刷掉以后跑到知乎洋洋洒洒写了几千字从全方位多角度把我们组连带整个中国字幕组圈子从头到脚喷了一遍的。
所以我们就逐渐从考官直接对接，变成招募了专门的抗压能力强的前台接待男姐姐去对接，一直到现在我们终于决定完全移除真人对话，所有考核内容全部放在网站上，然后邮件联系，基本杜绝了网爆的可能。

如果你没经历过这些年社会的毒打，你肯定会觉得我们为什么要变得这么冷冰冰的没有人情味。如果你没被那些眼高手低的人骂到脑溢血，你肯定想我们为什么要让那些人圆润地转动到远处。

[Perry]

有可能是作者经常被这些小白问题受到骚扰，所以保险起见加进了 doc 。

[loading]

建议楼主看一次《提问的智慧》，等你也有一定水平的时候，你会发现那些张嘴就问的人很烦，这个文档的作者可能是以前太热心，现在心烦了。

[sidkang]

认同，文档的写作方式确实有言下之意的成分，没有必要这样。

[shakoon]

我搞的某个产品最早只有几页简要说明，后来增加了一些流程图和截图，再后来到去年底大版本升级重写时，已经有五万多字，几百个截图了。原因就是用户的智商真的是没有下限的，要是不写清楚，后续技术支持能把人逼疯

[zzc1368129224]

被问烦了呗，还能写详细的文档已经很不错了，极端点的直接没有文档或者删库跑路

[Vindroid]

因为读者水平的高低差确实大，大到你没法想象。当一个人遇到许多不会读文档，啥基础都没有还非得用这类技术向工具，还脸皮很厚一个个配置项追问的时候，你的心态很可能也会像这位作者一样用类似嘲讽的说明写出这段话，虽然这类人会无视你的说明，继续提出一堆明确有说明的问题

[juzisang]

小白还以为自己是大爷的人还挺多的，Github 有个几十个星星的项目，都时常有人不会装，上来就是发个 Issues 骂你是垃圾，导致我点开那个项目的欲望都没了，时常有这种人的话，帖子里这项目作者的语气已经很好了，要是我直接就开骂，答都懒得给你答。还有，如果你觉得文档不好，你可以自己提个 PR 改一下呗，我相信作者肯定乐意接受

[shiguiyou]

我看了感觉没啥问题啊...

[monospace]

这个文档有什么问题？你觉得「有些东西没有必要一而再的强调」，这个项目又不是只给你用，还有一大把各种水平、各种经验的人也会用。作者尽量把不必要的发问和一些常见问题写在文档中，不好么？

[superfatboy]

看来时没有被小白毒打过

[zer0fire]

虽然把用户当白痴, 但是他写了很详细的稳定
现实里就是刀子嘴豆腐心
动漫里就是傲娇

[aliveyang]

作者性格比较直吧，不过文档很详细了

[youxiachai]

lz 是真不知道其实还真有不少中小学生用户?

[kinglisky]

那个有文档就已经很好了。。。

[sandman511]

同意楼主 直接后面放个 idea 链接就行了 还要鉴于读者水平 人上人

[Maiiiiii]

可以看一下 issues 历史

[kujio]

看教程的就是小白，不是小白也不会看教程。
既然这样是不是：鉴于读者的识字水品以下课文里不认识的字在课后有标注；鉴于读者的英语水品不认识的单词在课文后有释义；
对于已经确定的对象群体，不用刻意的再强调了，刻意强调虽然可能跟作者性格有关，但确实会令部分人感到不舒服。