ITPub博客

关于技术文档

原创 作者:jeanron100 时间:2018-04-13 09:28:52 0 删除 编辑

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

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

  1. 理念型文档,不会描述细节,是对一种思想的阐述

  2. 设计型文档,不会太笼统,会有一些整体的设计,会对纯思想的内容做一层抽象,结合应用场景的解决方案。

  3. 操作型文档,里面会有很多的技术细节

  4. 流程型文档,这种文档的主要是做一些铺垫和补充,比如有些内容简介,制度规约之类的。

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

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

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

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

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

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


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

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


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

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

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


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

请登录后发表评论 登录
全部评论

注册时间:2012-05-14

  • 博文量
    1499
  • 访问量
    14154518