大纲
- 回顾 17 年，文档写作泛滥、深度不足
- 重申文档写作的必要性
- 文档标题格式
- 文档迭代更新
- 文档上线
回顾 17 年，文档写作泛滥、深度不足
文档泛滥体现在：同一主题创建多个文档、同一题目创建多个文档、甚至同一内容补充更新时也创建了多个文档，经常出现的现象就是一个功能点每个人都只写了自己所涉及到的一方面，项目文件夹内的文档太多反而不方便查询信息。
单方面的思考为什么会出现这类情况：
- 不理解项目文件更深层的协作意义，只是作为自己的记事本在用
- 被点名整理文档，为了工作而工作
- 文档写作没有规范，大家无所遵从
文档写作深度不足体现在：不理解 markdown 存在的意义，笔记中会出现各种颜色、种类的字体；甚至基本的 markdown 语法错误随处可见；文档主题表达的完整性；迭代更新的后续动力。
markdown 是纯文本写作，拷贝内容至印象笔记中时请忽略样式，ctl/command + shift + v, 需要样式时请使用 markdown 语法表达。
重申文档写作的必要性
- 需求文档方便同事间协作交流，避免重复解释或信息传输错误
- 功能文档增强开发同事的思考，图文描述不清的功能无法验收
- 项目文档梳理各个服务的配置，避免手工操作时失误
- 部署文档记录各个服务的部署，避免后续运维的失忆
- 说明文档自定义主题，根据实际需求解释内容
- 培训文档讲解知识点，共享知识助力团队建设
所有文档共同具有的特性：
- 单一性：写作一次，被 N 个人询问只需要共享 N 次
- 跌代性：主题表述有误、信息过期需要更新，只需要更新文档内容即可，一次性共享给关联的所有同事
- 确定性：遇事不靠记忆，找到对应文档，白底黑字，不存在不确定的信息；必要时及时更新文档
- 交付性：完成了功能开发，还需要交付部署信息、配置信息、功能说明文档，而这些只需要把开发过程中的文档整理出来即可
文档标题格式
统一文档标题格式：主题名称 - 文档标题
已经在使用的主题名称：
- 需求文档
- 数据文档
- 技术文档
- 开发文档
- 项目文档
- 部署文档
- 说明文档
- 培训文档
可以根据需要自定义主题名称，符合标题格式即可。有更佳的标题格式欢迎交流讨论。
文档迭代更新
文档之所以会泛滥，就是不懂得迭代更新文档。
做好迭代更新就要坚持对主题名称及文档主旨，相同的主题及主旨已存在，自然就应该去更新已存在的文档；
什么时候去更新已存在的文档，什么时候去创建新的主题文档，这个火候没有明确定义，可以清晰的表述出自己的理解就可以。
盲目、随意的创建文档要点名批评，希望新的一年，文档数量不用太多，多关注内容深度。
文档上线
功能稳定后，技术文档、培训文档主题表述清晰，有助于客户、新同事理解产品的特性，都会吸纳到在线 gitbook 中；
文档的数量与质量已经成为考核团队成员的评判依据之一，避免性格内向的同事被忽略或低估了他们的工作成果。
网友评论