关于技术文档

关于写技术文档,我觉得是很多做技术的同学头疼的,因为写起来确实有很多注意的细节,很花时间和精力,而反过来说,做技术的同学更头疼的是,工作中竟然没有文档说明,没有了文档那么就是个人主义了,所以文档的事情对很多人来说是一种比较纠结的情况,有些鸡肋的感觉。

从我的理解来看,文档是对你工作成果的一个输出,我的认知,文档大体有几类:

  1. 理念型文档,不会描述细节,是对一种思想的阐述
  2. 设计型文档,不会太笼统,会有一些整体的设计,会对纯思想的内容做一层抽象,结合应用场景的解决方案。
  3. 操作型文档,里面会有很多的技术细节
  4. 流程型文档,这种文档的主要是做一些铺垫和补充,比如有些内容简介,制度规约之类的。

如果是上面的文档中,我觉得很多人对设计型文档和操作型文档会更感兴趣,而对上领导来说,其实对于理念型和设计型文档更感兴趣。

所以不同的角度看待文档的感觉和初衷还是有一定的差别的,越是细节的文档可能更新频率和内容变化就越大,而作为通泛统一的思想和设计,可能会比较稳定。

你说写文档好不好,我觉得这个问题确实得看工作的情况。对很多人来说写了额大量的流程型文档,他会觉得比较空虚,这种不充实的感觉主要是因为他没有涉及到做一件事情的核心,只是做了一些外围的事情,这个时候你说文档好不好,肯定不好,在我早期的工作里面,其实我是比较排斥这类文档的,但是作为工作的流程需要,还是需要这样一个形式,所以这可能不是一件好事,但是为了工作能够顺利开展,事情还得做,文档还得补充。

而工作中,你的工作成果和技术积累,其实就是通过文档的积累整理出来的。我举三个例子。

首先第一个是文档库的事情。

文档库是很多公司都在使用的技术手段,如果我们要重新设计一个文档库,就会把他规划的很细很全,但是实际去写文档的时候,会发现事情比预想的要难一些,因为从业务和技术两个维度,技术上都可以实现,但是具体去操作的时候就有很大的差别。

第二个是运维开发文档的事情。

为了提高公司同事对于运维开发的一些基础技能提升,我和兄弟部门发起了一个运维开发的培训。但是培训毕竟会有一种流于形式的感觉,很多人过来听就是单纯的来听听,也压根没打算做出什么样的东西来。所以从理念和态度上来说,这个事情的意义和实际的应用能不能很好的结合起来,预期和结果还是会有差距的。所以我们准备对已有的技术分享做一层沉淀,通过一些内容上的调整和梳理行程一个较为系统的文档,如果新员工来了之后,就会少走一些弯路。这个时候这个文档的重要性就体现出来了。

第三个是工作成果文档的事情。

比如我们前期做了很多的预研工作,也做了很多的测试,最终从报告的输出来看,其实文档的结论部分和思想的总结就是这个文档的核心了。

所以说前期我画了很多的脑图,规划图,设计图,同事感觉我想的已经很明白了,但是实际去做的时候会有各种因素的干扰,最终事情没有预想的那么好。从工作成果的角度来看,你似乎很难拿得出一些亮点成绩来。这对我们的工作积极性和对于工作的影响是有很大,没有文档的产出,你的成果就很可能不被重视起来,同时你工作的时候也会比较尴尬,可谓是困难重重,我早期的工作就吃了很大的亏,很多事情浮于表面,一直美欧推动起来,和这个还是有很大的差距的。

如果说文档的编写有什么技巧,我觉得一定是有一个系统的认识,如果为了写文档而写文档,那么文档的质量会有很大差距,这种情况是尽可能少写这类文档。

本文分享自微信公众号 - 杨建荣的学习笔记(jianrong-notes)

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2018-04-12

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

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 文档知识库的演进和小结

    本文是今天下午在我的自动化运维群做的分享,群里每天都有一到两个主题的分享,目前来看效果还不错。正文如下: 我看过很多公司的知识库,干脆叫它文档库也可以。总体来...

    jeanron100
  • 从生命周期的角度来规划数据库运维体系

    最近在和团队规划OKR目标的时候,我们讨论了很多问题,我先抛砖引玉,列举了一些现有的问题,打算按照推导的方式:

    jeanron100
  • Django初探(二)

    之前写过一篇Django的介绍,简单部署之后就没有深入跟进了。 Django初探 上周末去广州参加技术大会,在往返的飞机上,自己调试了下Django里面的内容。...

    jeanron100
  • 为啥开发的文档能力是核心竞争力之一

    在开发团队里面一般产品的文档能力会比较强,很多开发的文档能力都非常弱,在我看来文档能力是一个程序员核心竞争力之一,文档能力强才能实现能力的快速发展。为什么语文在...

    用户5829239
  • DevOps 下的文档及其版本管理之实战

    在上一篇《 DevOps 下的文档及其版本管理之设计篇》中简要介绍了文档及其版本管理的设计思路,该篇将讲述其实际操作部分的内容。上篇文章中讲到文档信息保存在两个...

    DevOps时代
  • 文档!文档!文档!重要的事情说三遍!

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

    风间影月
  • 程序员既要写好代码,又要写好文档

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

    用户1289394
  • 技术文档如何编写?

    谢伟
  • 谷歌软件工程师是怎样写设计文档的?

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

    深度学习与Python
  • 总监突然把我拉进了一个群……

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

    TAPD敏捷研发

扫码关注云+社区

领取腾讯云代金券