关于文档和写作吐槽,你也是这样想的吗? | 技术写作什么鬼

大家好,我是睿齐,一个自诩“最懂技术的传播者,最懂传播的工程师”的技术传播者。

在庞大的程序员群体中,可能有相当一部分属于文档纠结体质。CSDN程序人生(ID:coder_life)曾发起过的一个话题讨论:一人一句程序员日常牢骚,不许重样,在精选留言区,排名第一位的留言是:

其他和文档相关的热门留言还有:

所以,你是不是也对文档怀着这种既爱又恨的复杂心情呢?

作为一名技术文档工程师,日常工作中与研发工程师对接文档工作,基本相当于家常便饭,能够听到的吐槽就更多了。不过很多时候会感觉,很多所谓的槽点只是因为缺少了解和理解。所以今天就来聊聊,那些关于文档和写作吐槽,告诉我,你也是这样想的吗?

文档没用,为写而写,写了白写。

确实,文档的开发成本非常高。也正是因为如此,去定义要不要写一个文档,通常会慎重地考虑投入产出比。如果说是“没用的文档”,根本不会去开发;换句话说,只有真正被使用的文档,才会被定义。

我们之所以常常感到“文档没用”,很多时候是因为,文档的质量不能满足使用需求,无法有效传递信息,不得不借助于口传身授,并不是文档本身没有用。

写文档是浪费时间,没时间写文档?

对于研发文档而言,文档本身就是研发成本,代码时间只占研发时间的30%;写文档是整理思路的过程,打字的速度应快于思考的速度;没有文档,后期也可能会花费更多的维护成本。

研发都懂,没必要写那么多?

我们在策划对外交付的用户文档时,确实会要求用户具备某种程度的专业水平。但即便如此,也会以短板用户为准,不默认用户必然全知全能。

面对面交流效率高,不需要写文档?

研发项目中,50%的时间是用来沟通。多人协作场景,1对多沟通场景,会出现沟通效率问题。所以随着公司规模越大,沟通成本也会成指数级地增加。

问题我已经考虑得很清楚,只是不会写文档?

写不好文档的根本原因是“没想清楚”,提高文档写作能力的本质,实际上是提高分析问题的能力,提高设计系统的能力。

文档就是吹牛皮,要写得高大上?

我们在这里讨论的文档不是市场文案,也不是创意文案,而是技术文档。这类文档的主要作用是提高沟通效率,提升对“思考过程”的管理,所以客观实际最重要,不需要加工创造,甚至明确要求避免使用形容词。

样式高于内容?

很多人会认为,排版整齐一点,文档质量就更高——对于对外交付的文档,一定程度上,是的;对于内部使用的研发项目文档,则大可不必。之前我和很多研发同事沟通过文档问题时,会反复强调:我们首先看重的是内容质量,样式排版只是锦上添花。

文档都是给别人写的,对我有什么好处?

其实,文档是一个知识和信息的生态,我们每个人都是互相输出价值;而且文档的目标是高效沟通,和知识积累,无论对公司还是对个人,都是宝贵的资产。

最后需要说明的是,部分统计数据摘自资深技术专家章淼老师的怎么写项目文档,墙裂推荐这篇文章。

说了这么多,是不是可以解决了你心中的一些疑惑呢?如果你还有更多关于文档和写作的吐槽,不吐不快那种,快到评论区来给我留言吧。如果觉得我说得还怪不赖的,就帮忙点一记免费的“在看”,支持一下吧?

相关文章:

新鲜事:74%的初级程序员认为这最让人恼火 | 技术传播

怎么写项目文档

其他推荐:

实施:GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播

技术传播是一片蓝海 | 技术传播

访谈:TC无处不在,只是我们没有发觉 | 技术传播

这次他们说好要“讲真的” | 传播

在座都别吵了,你们还有我 | 技术传播

一本培养强迫症患者的说明书 | 技术传播

就像用心做好日本料理 | 技术传播

顽固的老头子与无聊的说明书 | 技术传播

转战新媒体 | 技术传播

评测:王者荣耀的用户帮助系统 | 技术传播

让爸爸妈妈也能享受到科技发展带来的便利 | 技术传播

企业级信息管理系统初创方案构思 | 技术传播

 

睿齐

技术传播从业者

品牌内容策划

自由摄影师

自由撰稿人

汪力迪

公众号:techcomm / htstory

微信号:bgrichi

邮箱:hash_0813@163.com

  • 1
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值