「好文档自己会说话」我们的文档如何更直观的传达信息
日常沟通中,我们把一件事情讲清楚,挺难的。我们经常遇到这样的情况,一个人滴里嘟噜滴里嘟噜滴里嘟噜滴里嘟噜滴里嘟噜滴里嘟噜滴里嘟噜滴里嘟噜说了一堆,听的人一脸懵逼。
文档亦是如此。比说还难。 Easier said than done. → Easier said than written. 。 小学作文我们就被教导:首先要有中心思想,然后围绕中心思想展开。 这个原则对于任何文体都如是。描述大象,你花了太多篇幅写猪,显然不OK。讲述如何进行项目管理,你写的都是团队管理/技术设计,显然不OK。讲述张三很有钱,你却是一笔带过,通篇讲张三儿时的苦日子,显然不OK。
那么,有没有一些工具或方法,来辅助我们把文档写得更严谨、更直观呢? 本文进行了一部分整理。
文档标题传达关键信息
有开发同学分享《如何写一篇项目文档》,而在文章内容里写的都是软件开发设计方面的事项,如功能点拆分、接口定义、数据结构设计、流程图用例图。 因此,此文档的标题可以改为《如何写一篇软件开发设计文档》。
文档开头,先描述清楚文档的背景或概要
✔文档开头,先描述清楚文档的背景
没有比较,就显不出优势↓
|
vs |
|
✔文档开头,先描述清楚文档的概要
设定段落层级结构
跟我们写的作文或读的文章一样,都会有分段。分段的作用大家自行脑补。
必要情况,可以使用特殊符号,来进行强调,或信息分隔。我们组的小wangjie同学的文档是最佳实践。
添加目录
当文章的内容量较大时,可以使用清晰的目录,协助读者快速了解。
文章里的附图,尽量一眼就能直观看出来
下面设计文档里的这张流程图,太小了。
你肯定会说,点击就可以看大图。 - - - - - 如果不用点击就能看到清晰的业务流程,难道不是更好吗?
表达一组进度/占比,别再硬生生地堆砌数字了
我们系统的《每日系统监控报告》里,下面的CPU监测,一眼就能直观看出来各机器的CPU使用情况。这比直接罗列或堆砌56%、54%、40%要好上千倍。
colorful(颜色是个好东西)
尽善才能尽美,信息要完善
当然,最重要的,还是”把话说清楚“(内容要清晰)
微信官方文档中,对于appId、openId、unionId 的含义,有如下解释。相当清晰!
上文摘自公司内部confluence知识库
分享:「好文档自己会说话」春节倒休计划表
2024蛇年春节临近,要过年了,中国的传统大年,一年到头,不管大家身在何处,总要回去跟家人一起团圆几天。工作方面呢,按照历年惯例,得提前收集部门内每个人在假期前后的倒休安排。
一个组长创建了在线表格,发到TL沟通小组里,供大家填写。
很快,另一个组长也创建了在线表格,并建议大家使用这个。
比较两个表格,后者更易于大家去填写,对吧?
EOF
当看到一些不好的代码时,会发现我还算优秀;当看到优秀的代码时,也才意识到持续学习的重要!--buguge
本文来自博客园,转载请注明原文链接:https://www.cnblogs.com/buguge/p/18005028
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· 清华大学推出第四讲使用 DeepSeek + DeepResearch 让科研像聊天一样简单!
· 实操Deepseek接入个人知识库
· CSnakes vs Python.NET:高效嵌入与灵活互通的跨语言方案对比
· Plotly.NET 一个为 .NET 打造的强大开源交互式图表库