「好文档自己会说话」我们的文档如何更直观的传达信息
日常沟通中,我们把一件事情讲清楚,挺难的。我们经常遇到这样的情况,一个人滴里嘟噜滴里嘟噜滴里嘟噜滴里嘟噜滴里嘟噜滴里嘟噜滴里嘟噜滴里嘟噜说了一堆,听的人一脸懵逼。
文档亦是如此。比说还难。 Easier said than done. → Easier said than written. 。 小学作文我们就被教导:首先要有中心思想,然后围绕中心思想展开。 这个原则对于任何文体都如是。描述大象,你花了太多篇幅写猪,显然不OK。讲述如何进行项目管理,你写的都是团队管理/技术设计,显然不OK。讲述张三很有钱,你却是一笔带过,通篇讲张三儿时的苦日子,显然不OK。
那么,有没有一些工具或方法,来辅助我们把文档写得更严谨、更直观呢? 本文进行了一部分整理。
文档标题传达关键信息
有开发同学分享《如何写一篇项目文档》,而在文章内容里写的都是软件开发设计方面的事项,如功能点拆分、接口定义、数据结构设计、流程图用例图。 因此,此文档的标题可以改为《如何写一篇软件开发设计文档》。
文档开头,先描述清楚文档的背景或概要
没有比较,就显不出优势↓
|
vs |
|
设定段落层级结构
跟我们写的作文或读的文章一样,都会有分段。分段的作用大家自行脑补。
必要情况,可以使用特殊符号,来进行强调,或信息分隔。我们组的小wangjie同学的文档是最佳实践。
添加目录
当文章的内容量较大时,可以使用清晰的目录,协助读者快速了解。
文章里的附图,尽量一眼就能直观看出来
下面设计文档里的这张流程图,太小了。
你肯定会说,点击就可以看大图。 - - - - - 如果不用点击就能看到清晰的业务流程,难道不是更好吗?
走点心,就会更清晰
我们系统的《每日系统监控报告》里,下面的CPU监测,一眼就能直观看出来各机器的CPU使用情况。这比直接罗列56%、54%、40%要好上千倍。
尽善才能尽美,信息要完善
分享:「好文档自己会说话」春节倒休计划表
2024年春节临近,要过年了,中国的传统大年,一年到头,不管大家身在何处,总要回去跟家人一起团圆几天。工作方面呢,按照历年惯例,得提前收集部门内每个人在假期前后的倒休安排。
一个组长创建了在线表格,发到TL沟通小组里,供大家填写。
很快,另一个组长也创建了在线表格,并建议大家使用这个。
比较两个表格,后者更易于大家去填写,对吧?
EOF
当看到一些不好的代码时,会发现我还算优秀;当看到优秀的代码时,也才意识到持续学习的重要!--buguge
本文来自博客园,转载请注明原文链接:https://www.cnblogs.com/buguge/p/18005028