程序员文档写作能力(二)-大三段式构架你的文档

发布时间:2024-10-26 18:01

内容概要

我们今天先从最最常用的平日工作中经常要用到的你的主管、老板让你留文档这种常用技术文档(含设计文档)入手来入门吧。

第一大段-虎头

哎,这个名字起的好。今年是虎年,祝愿各位虎虎生威。

为什么叫虎头?虎头威武吧?虎头是不是很美?它有金黄色的毛发、额头有着明显的“王”字,用国家地理杂志形容老虎,那真是“一头美丽的动物”。

程序员文档写作能力(二)-大三段式构架你的文档_第1张图片

从感观上来讲是不是夺人二目

老虎吼一声,那是自带次声波的,一般狗啊、猫啊、其它食草类动物包括人类听到老虎如果近距离吼直接四脚是“瘫软”的,是不是。。。“先声夺人”啊?

回到正题来。

业务需求你要对它进行设计、或者是出于某个创新目的你要做设计,上手先说一下这个需求的背景。

业务需求背景属于“虎头”。

你不要无脑只是copy一下业务的需求简介,笔者近10多年来包括接触的好多供应商讲标,一般这个需求背景写的好的往往者是深入研究过业务需求和了解本行业眼下潮流知道基本痛点的,那是一种基于自我理解后对业务需求的“再翻译”

要写一下:

  1. 业务是出于什么目的出的这个需求;
  2. 这个需求解决了本企业、运营中的什么痛点;
  3. 我是如何理解这个需求的;
  4. 我准备怎么去满足这个需求;

这个很重要,这就是“业务理解”能力。我是一个搞技术出身的,可是为什么近10年来变得口口声声业务、业务呢

哎,各位!再回到我在10年前写过的博客里你们可以去翻一下。什么叫业务IT界的业务是运用技术手段去解决企业在运营中的重复工作和痛点,为企业在运营和生意上形成不对称竞争优势的手段而己

我10年前就写过了,对于科学家来说他的业务可能是:天体运动。对于医生来说它的业务是发现早期癌变组织。

业务就是“解决方案”,解决方案不纯粹是打单、跟单、做财务,而是一个企业要如何引流、挣钱、增单的一种“实际操作的抽象逻辑”,这个抽象逻辑去用IT的语言再实现。因为业务本身=技术实现+企业运营抽象逻辑一切都是业务方案你把性能提高是为了顶住更多的流量、更多的单量,性能优化其实也是“业务解决方案”,一切都是业务解决方案。

请自动把业务和解决方案划上等号吧!

借此多说一句:运营逻辑=市场销售=挣钱手段

这点很重要,技术团队的“业务方案”都要符合运营逻辑。如果两者大相径庭,你这个方案是不合格的。那么我要做设计前我写一下我对你提出的业务逻辑的理解。这个理解可以错、可以对、可以有偏差、也可以有争议。

这正是业务和技术相互进一步沟通、融合的手段。我从来没有看到过技术解决方案一次就可以满足业务需求的。

这本来就是一个团队工作,双方就是就这个业务理解和业务需求进行互相进一步探讨才能形成“接地气的解决方案”。

技术通过这个“需求理解”的虎头可以借此告诉业务方,你的这个需求有90%可以满足,有10%因为等等诸因素需要另一种满足手法。

有问题就说,有问题才是好事。碰撞才能出火花!

业务借着技术写得这个“需求理解”也能知道技术是不是可以100%满足或者是有我不知道的坑存在?业务不是万能,业务的话也不是100%必须听,业务也是人,是人他是想不全,是人都有自己擅长的领域和自己不擅长的领域局限。

因此,需求理解是非常非常重要的。

设计原则属于“虎头”

在上手写完业务背景理解后,写上你的设计原则。

什么叫设计原则?为什么这篇要写在业务需求理解的后面。

这叫“因为。。。所以。。。”因为有了这样的需求,所以我准备使用如下的“方法论”来设计,它们分别为1、2、3、4等等等。。。。。。

不需要多,以1,2,3,4控制在100-150字了不得了。

需求如果不能满足或者业务提出的这个构思有风险也属于“虎头”

前面说了,业务也是人、业务有自己的领域局限。比如说业务对于某个需求存在“网络个人信息安全法”上的知识的欠缺,此时IT有Information Security也有架构,一眼看出你这样做的话或者你没考虑这些因素,这种需求做出来后你的网站都要被“干掉”。或者说你这个需求不能找开发而是要去找大数据找BI否则APP或者网站会被你搞垮。

此时你就需要把这些内容写出来,并且以相关风险,或者是“进一步需要澄清”,或者是“需要业务确认”,然后以1,2,3,4这样的方式列出来就行了。

虎头的内容不会太多。它起到的作用就是:

  1. 有事拣重点说;
  2. 有问题有风险早点报;
  3. 我想要干什么、怎么干抽象总结一下列在最前面以起到重要告知为目的以引发进一步可能的探讨,不要怕探讨,群策群力才能把方案做了更完善;

这也是一种向上或者向下管理方法中的“管理心理学“。

有一些领导或者平级是综合能力专家,有一些是技术专家,它们有时看前面那300来个字就知道你这样走下去是否可行、是否有偏差甚至后面可以不用多看就知道你的思路对不对或者你的方案靠不靠谱,亦或者直接觉得这个需求在眼下来说太占资源又不能带来直接经济效应那也就把优先级降低了。

说白了一点这叫“不要浪费大家时间”。大家想一下,比如说有一个方案,我看过建筑、造房子的方案还,非常非常有意思,给你们说一下:

当地要造一幅48层的标志性建筑,设计书BLA BLA BLA说了一堆有140多页,最后两页告诉你地下土质疏松只适合建造不超过4层楼的房子并附上地质探测报告。140多页啊?come on,一群人要看多少时候?你不能把这件事放在一开始就说呢?那边挖土机已经调了15台过来了都,油费,运费,高速公路过关费。。。唉。。。

还有一件事也是很好玩,一个医生对着家属讲了3小时的近乎于“免疫学入门”级话术,最后只花了1分钟来告诉家属这个人已经救不了了

你们说,这种“沟通”这种“话术”。。。碰到的很多技术人员如果没有经过专业培训都会陷入这种上手给你BLA BLA BLA,而这样的人如果成为了习惯、不自我认知,随着时间一长、次数一多,领导或者平级的同事真的不需要再多听他说话了或者干脆不再多用他去做设计了。

因此,虎头的本质是体现让沟通更高效

第二大段-猪肚

程序员文档写作能力(二)-大三段式构架你的文档_第2张图片

当然,猪头猪后半部一般我们是不太会去吃的,至少普通大众是不会去吃的。

大家想想猪肚子,有哪些可以吃的?

  1. 麻酱爆肚;
  2. 上海还有一道本地名菜叫青椒炒肚皮,大火一开、小锅一翻,那叫一个嫩呀,那叫一个爽口呀,就热吃,咪上一口“石库门”,那叫一个鲜呀;
  3. 炒肥肠?霍。。。伴着花椒,炒一大碗,看了口水都流下来了;
  4. 夫妻肺片;
  5. 猪排,淮海路著名的存在了近90年的老克勒炸猪排+罗宋汤;
  6. 里脊肉;
  7. 还有很多很多,能举几十种菜出来;

猪肚是不是很丰富哈

因此第二大段内容叫猪肚,是代表了第二大段里的东西绝对少不了、且很丰富还“很好吃”

因此我们会把如下内容都归于第二大段中,它们分别为:

1. 技术栈

准备使用的技术栈,它可以为一个“表格”,分成3列:

  • 第1列为:序号
  • 第2列为:使用的技术栈名如:JDK版本、组件版本
  • 第3列为:技术栈说明或者是为什么要用这个组件,很简要的说明一般不超过20个字;

ItVuer - 免责声明 - 关于我们 - 联系我们

本网站信息来源于互联网,如有侵权请联系:561261067@qq.com

桂ICP备16001015号