HbDoc

协作文档撰写指南

文档作为团队内部信息传递/沉淀的主要媒介，撰写时应包含有助于此文档顺利使用的相关信息，以便使用者能依据文档顺利开展工作，减少沟通成本。特此建立此文档撰写指南，供创建文案、规约、纪要、策划等文档时参考，方便团队协作。

文档结构

常规文档结构一般包括五大部分

• 头部说明 ~ 文档背景、适用情境等有助于队友正确使用本文档的信息
• 正文 ~ 文案、规约、纪要、策划等内容的正文
• NEED ~ 要达成文档内容所驱动事务的目的，需要谁做什么（若无可忽略）。也不一定汇总到一个板块，在正文中及时说明也 OK
• 参考资料 ~ 有助于队友更好地使用本文档的资料链接
• ChangeLog ~ 记录文档修订过程

各板块要点

头部说明

常规要求

一般来说，应该在文档第一行就明确文档的性质：文案？规约？记要？策划？ ...

不同性质的文档头部说明有不同的侧重点，但总体来说，需要给出文档的背景信息，比如：

• 简要说明背景要素和提出正文的原因，即给出文档的 5W1H ，比如本文第一段头部说明
• 说明方式可以是简要描述，也可以链接相关任务卡及相关过程讨论 Issue

以便文档使用者知道原因、进展，根据已有内容获取足够信息以判断文档内容是否 OK ，并给出建设性建议。

各性质文档头部说明侧重点

• 若正文是微信原创图文文案、对外发布的邮件通知等文案，头部说明一般要有
  • 公司近期运营着力点
  • 过往运营节奏、数据分析
  • 本次发布目标、发布时间、负责人
  • 发布后的计划（发布后的微博、机器人朋友圈、各微信群的推送计划）等
• 若正文是活动策划，头部说明一般需要
  • 基本同微信图文
  • 若是系列活动，还应加上之前活动的数据、经验分析和调整方向
  • 若内容太长，可将某些部分另起文档说明，加上超链接即可
• 若正文是规约/手册，头部说明一般为
  • 适用人员
  • 适用情境/环境配置建议等
• 若正文是纪要，头部说明一般为
  • 背景，也就是为什么会有这次沟通
  • 参与者，以便其他看到文档的人知晓这些是谁达成的共识，了解谁（不在现场）不一定知晓
  • 沟通发生的时间时长地点，以便知晓是在哪里发生的
  • 录音链接（我们公司沟通录音一般上传到公用百度云账号）

总之，一定避免没有任何背景信息介绍，一开篇直接是正文的情况，尤其需要发给别人修订、审核的文案。毕竟这样的无头文档容易让看到的人摸不着头脑，不清楚这个文档是否适合自己/当下情况使用，甚至在无正确理解的情况下进行下一步操作。

文档正文

展开文档正文，该怎么写就怎么写吧。

若是纪要这类过程性文档，有良好团队知识管理习惯的队友一般还会及时把共识同步更新到其它相关文档中，比如战略会议后，通常需要和纪要同步更新关于定位/季度目标/公司品牌使用规约等文档。毕竟常用的还是长期使用的文档，而非每次翻过往会议纪要看最新共识。

NEED

列出需要谁配合做什么来完善这个文档/推动这个事情。通常列成 checklist 的方式，比如：OM2py 结业典礼 筹备 checklist

• checklist 注意描述清楚 who/when/what，并在微信群或项目管理平台等协作界面知会对方
• 尽可能给出成果链接地址
  • 可以由挖坑的人给出链接地址，以便填坑人顺利填坑
  • 也可由填坑人按照团队共识上传成果给出地址，以便其他同伴使用该成果
• 如果有必要，还可以开个任务卡、issue 来跟进 NEED TO DO 的完成
• 若没有，可不写

参考资料

列出文档中涉及到的相关资料出处，以便相关参考资料内容变化后看到该文档的同事也能及时看到最新版本。

ChangeLog

记录修订过程，一般为 日期+人员+动作 。举例：

151129 闪闪创建

• 请一定注明创建人，以便日后有疑问时方便追踪源头求解清楚
• 使用倒序，以便一眼看到最近更新

其它

以上主要为协作时创建文档的内容建议，写完内容就完事儿了吗？想得美！---- 命名更是关键：它看似简单，实际体现了你对你的对象在当前体系中的关系/作用的理解深度，往大了说，命名还直接反映了你对整个资源结构的理解。俺也是踩了好多坑才慢慢明白……

好的命名能让队友一眼识别文件内容需要时及时调用。别做猪队友，从了解团队文档命名规约开始 XD

PS.对产品文档了解不多，所以没有列出。看到本文的你若觉得有啥需增补修正的欢迎提出：D

ChangeLog

• 160211 闪闪迁移到公开库
• 160110 闪闪重构
• 151129 闪闪在团队私有库创建一稿