Wow4j Wow4j
首页
个人使用说明书
后端开发
前端开发
测试开发
运维开发
大数据开发
产品&UI交互
团队管理
软技能
他山之石
开源产品
敬请期待
GitHub (opens new window)
首页
个人使用说明书
后端开发
前端开发
测试开发
运维开发
大数据开发
产品&UI交互
团队管理
软技能
他山之石
开源产品
敬请期待
GitHub (opens new window)
  • 概要
  • 如何一键生成项目树形结构
  • Markdown书写利器Typora最佳实践指南
  • 浅谈如何提升职场晋升力
  • 复盘的技巧:深度复盘的三个步骤【转载】
  • 好文档最佳实践

    • 中文技术文档写作规范(Markdown版)
    • 如何写出一份合格的技术文档
    • 字节跳动优秀文档 8 大秘籍
      • 1. 无从下手?很多时候是没「想清楚」
      • 2. 从「用户视角」出发
      • 3. 用好的『结构』让读者理解你的思路
      • 4. 选择合适的「呈现形式」,突出重点
      • 5. 保持「精简」
      • 6. 「清晰」表达,别让读者猜
      • 7. 「细节」决定成败
      • 8. 保持输入,不断「迭代」
    • 写好文档检查清单
    • 软件手册范例
  • 软技能
  • 好文档最佳实践
timchen525
2022-11-29

字节跳动优秀文档 8 大秘籍

原文地址:字节跳动优秀文档 8 大秘籍 (opens new window)

# 1. 无从下手?很多时候是没「想清楚」

大多数情况,文档是工作的一种呈现方式。如果说文档写得好是「表」,那么「里」其实包含了两个层面的问题:

  1. 我们有没有想清楚? - 「想清楚」是所有文档创作的前提。这考验着我们对这件事的思考是否深入、逻辑是否自洽、准备工作够不够扎实;
  2. 我们有没有把这件事讲清楚? - 有没有展示读者关心的内容,且清晰易懂。

在平时的工作中,工作不是在已知中重复,而是不断闯过新的难关。所以如果你感到「无从下手」,不要太慌。试着定义清楚要解决什么问题、 收集资料、发散思考,再逐步收敛出结论或观点。

完成这一步,我们就可以开始考虑如何呈现和组织信息了。

# 2. 从「用户视角」出发

将文档视作「产品」一样打造。

从这个视角出发,读者无疑就是这个产品的「用户」。那么如何最快地转换视角呢?试试问自己三个问题:

  1. 我沟通的目标是什么? - 以写一份「产品需求文档」举例,沟通目标就是「评审一次过」!那么文档写的内容,能不能帮助我达到目标?
  2. 我的「用户」都是谁? - 结合文档的使用场景去看,例如一份双月汇报材料,读者往往包括:管理者 + 协作者 + 信息同步对象;
  3. ta 知道什么? - 我清楚掌握 100% 的背景信息,但我的用户们知道多少?
  4. ta 想知道什么? - 假想一下,如果只让对方提 3 个问题,ta 会问些什么?

能想清楚这些问题,我们大概率对于要在文档里「写什么」有把握了。

# 3. 用好的『结构』让读者理解你的思路

就像一篇文章,文档往往也包含开头、正文、结尾,三部分内容各有分工。在这样的大框架下,正文结构就像骨骼,将文档要表达的观点串起来。

我们将每个部分拆分开看:

  • 开头: 好的开头让读者更快『代入』解决问题的情景。将背景、要解决什么问题、建议方案精简地总结在开头,让读者快速浏览后心理产生一个问号?紧接着我们在用正文解答读者的疑问;
  • 正文:正文的划分维度就像预告片,为读者展现了你的解决思路。在实际操作中,建议每个部分结论先行,论据紧随,这也被称之为「金字塔结构」;
  • 结尾:结尾主要起到「敲黑板画重点」的作用,加强读者对问题的理解,同时明确下一个阶段的动作。

# 4. 选择合适的「呈现形式」,突出重点

结构梳理清楚后,在具体的呈现形式上,也有方法可循:

  1. 借助图标
    • 涉及到大量数据的,选择表格比打一堆文字更一目了然;
    • 此外,还有甘特图、脑图、泳道图等不同的图形化表达方式,可以结合内容针对性选择;
  2. 通过加粗/标记颜色/斜体等方式高亮重点信息
    • 高亮内容适用于总结句或者关键数据,建议大家克制使用,否则会模糊真正的重点。

不过,文档并不需要参与「选美」。选择合适的呈现形式更多是为了清晰传递信息,但不意味着我们需要「过度包装」,花费大量时间去美化和修饰。

# 5. 保持「精简」

敲下每个字都是心血,是在不知如何取舍?试试以下技巧:

  1. 不要假设读者「什么都不知道」:避免事无巨细,信息过载;
  2. 善于归纳总结:有理论指出,人的记忆条目是 7(±2)条,归类之后会减少人的记忆成本;
  3. 对自己残忍一些!:拿捏不准的时候,问自己一个问题:如果去掉这部分,是否会明显出现信息的减损?如果答案不是一个肯定的 Yes,那就是一个肯定的 No。

# 6. 「清晰」表达,别让读者猜

在语言的表述上,简而言之就是三个字:说人话!

各种黑话和高深词汇并不会让你的文档看起来高大上,对读者来说反而是一种负担。一个简单的参考标准是:"新同学能读懂吗?"

在信息组织上,「不要让读者猜」也可以作为参考原则--读者看到第一句话产生的疑问,下一句话就给ta答案。

一个示例:如果在汇报中向 Leader 呈现"双月渗透率下贱",那么 Leader 的心路历程和你要呈现的信息大概率会是这样:

  • 哈,下降了多少? - 5-6月 PC 端渗透率下降了 3%;
  • 为什么下降了? - 经过分析,下降原因主要是ABCD;
  • 那有什么解决办法吗? - 接下来我们准备通过 EFG 等办法来提升渗透。

# 7. 「细节」决定成败

文档写好,临门一脚!但先别急。不断进行自我审查对于打造一篇优秀的文档至关重要,这几个坑我们邀请你一起避开:

  1. 格式检查:并列呈现的信息要对齐,否则你的"房子"看起来会歪歪扭扭;
  2. 错字要细节检查:错别字、大小写、全角/半角标点、单位保持统一、数字小数点等等。

有时候,一个文档写得太久,容易深陷其中无法自拔。所以在最后关头可以发给几个同事共同检查,或许会带来意想不到的发现。

# 8. 保持输入,不断「迭代」

好的产品需要结合用户需求不断迭代,好的文档也是如此。

例如,从知识库、公司内网等渠道选择"优秀作品"临摹;先去看这些文档分成几个板块,每个板块包含哪些内容,作者背后的思考逻辑是什么。将这些能够启发自己的文档收藏起来。

上次更新: 2022/12/07, 14:49:16
如何写出一份合格的技术文档
写好文档检查清单

← 如何写出一份合格的技术文档 写好文档检查清单→

Theme by Vdoing | Copyright © 2022-2023 timchen525 | MIT License
  • 跟随系统
  • 浅色模式
  • 深色模式
  • 阅读模式
×