如何练习L5 to L6的写doc能力

楼主在狗家某infra组升5有一段时间了，在组里是TL之一，专门负责一个技术领域。老板是去年转组过来的，对我们目前的整体算法和架构不是特别满意，让我做一些调研写一个大的提纲把可以提升的东西总结一下。我的doc写好后感觉方向和proposal都比较明确，headroom也很大，可以花半年一年的时间把系统性能提升很多。但老板表示我的idea都是above L5的难度，但对我写的doc不满意，觉得我的proposal是高于我的doc和presentation水平的…doc写作还达不到L6水平。

具体点就比如，他觉得我写的东西很难去follow，一上来列了很多表格总结，但没有解释清楚术语，以及目前系统是如何运作的（他说可能是因为他对我们组的东西还不足够熟悉，但要往更高level走的话，要让没有context的人也能知道你的doc重点）我其实之前跟组外的mentor聊了下我的doc，mentor觉得好像我说了太多为什么我们现在的系统不好，让人容易花太多时间去了解和关注于现有系统为什么不好，所以后来我才省略掉了很多背景概要，但省略掉又导致了读者不容易看懂，加上背景介绍这些doc就变的又臭又长。

我其实比较容易沉浸在技术细节，比如各种query分析和coding，但一旦要总结就会有点让其他engineer不知所云。感觉还是沟通能力不够，不太能简明扼要地把一个idea的重点展示出来。不知道大家有没有什么写作教程推荐，尤其是写strategy doc，roadmap这种，怎样能删繁就简，由浅入深。

写的再好很多reviewer们都不看，每次来meeting和傻子一样从头讲起，以前在亚麻不理解很多review meeting前15分钟强制大家安静读doc，来了狗才发现不少人还真是一个字不看就来胡搅蛮缠

你quote别人说的话里面已经cover写doc的重点了。
1>但要往更高level走的话，要让没有context的人也能知道你的doc重点 2> 加上背景介绍这些doc就变的又臭又长

不同doc的target audience是不一样的，举个例子roadmap这种doc target audience是向上的 （还有个作用是抢地盘），背景部分说的更是现状和将来的impact, audience更不关心技术上什么导致了现状；传统意义上的design doc是给peer看的，你可以上来就写assume audience with general context of, 再补一个go link 到detailed点的context doc。
我一般会抄UTL写的doc；他roadmap什么aspects讲了几句话，我也讲几句话。他画几个图，我个搞几个图。

另一方面是最近意识到的，non-swe director们基本不会阅读，再简单两句话能说清楚的东西，你不画个图，director就和傻子一样啥都看不懂。

多看看别人怎么写类似的构架设计，照着人家格式写，照着你觉得好的构架图做（抄），把给不同目标群体的文档分开（给老板和pm的多写总结结论多用图表，主要内容写重点，后面appendix加细节QA和reference，给下面eng的多列举技术细节和优缺点分析，侧重点都不一样），就是得多抄多练慢慢就好了。。而且每个组每个老板喜好也不一样

技术是为了需求服务，把重点放在如何满足需求上而非逐字逐句解释技术细节。

清晰的思路是从需求开始到满足需求结束，技术可有可无，没人关注你怎么实现，当然实现也很重要，可是你应该把实现做封装

推荐你找个company的mentor

很多谷歌的人真是欠去亚麻学习锻炼一下，一些L6写的doc也不咋样一坨狗屎

https://developers.google.com/tech-writing
随便搜的lol

来学习，多学多看总是没错的

1.多读paper可能的话写写paper。读paper的好好想想别人是怎么清楚的表述自己的idea的， 然后形成自己的风格；
2.上一些课了解美国人眼中的好的writing是怎么样的；
3.在自己的日常email中练习；
4.用chatgpt 反馈。