知识卡片
良好的规格说明书能简化事情:撰写技巧清单
对满脑子技术细节的人来说,撰写规格说明书最难的事情是有效判断该省略哪些细节、该在什么时候省略——撰写的全部意义在于用读者花最少努力就能理解的方式来描述事物,而复杂度常常被当作借口来掩盖内容本身撰写乏味或思想平凡。以下技巧能帮助达成这个目标:可以直接借用其他人写过的优秀说明内容,不必事事从零发明;避免行话和模糊语言,除非确定能真正帮助读者理解;保留旧的规格说明书作为遇到困惑时的参考资料;撰写时心中要有一个具体的读者形象——即便面对十人团队,也可以设想其中一位对当前技术不熟悉但足够聪明的人,想象如何向他解释困难的概念;对工具和图表保持”柏拉图式的关系”,不要爱上Visio或UML本身——图表往往只对制作者本人有意义,因为图表是撰写者理解某件事的方式,却不一定是向别人说明这件事的最好方式,有时一段好文字或随手画的草图比五百个元素的UML图更有效;分清规格说明书和参考资料的边界,只聚焦最常用或最重要的十到十五个案例,剩余细节另立独立文档;对复杂算法,先用伪代码或英文从高层次描述。另一项特别有效的技巧是:一旦有人对草稿中的某处感到困惑,花五分钟当面解释清楚后,紧接着问他”有没有更好的方式可以用在规格说明书里说明”——这个动作能持续改进理解,也比被动等待反馈更容易获得有价值的建议。
这张卡片看不懂?
这张卡片的反馈已满 10 条,暂时无法继续提交。
已有反馈 · 0 / 10 条
还没有人提交反馈。
在整书笔记中的位置
原书出处 · 1 处
- 第07章 撰写优秀的规格说明书 · 查看原书依据
当的复杂度,这就是判断的问题,最好让团队领导者决定。 但是,为了试着描述好事情,我还是提供以下撰写规格说明书时一些技巧,以及应当避免的事情: ·从其他规格说明书那里借用良好的说明内容(即使是其他人写的)。适当使用超文本(hypertext),如果需要,可以从网站上摘取有用的概要——团队领导应该鼓励这么做
参考来源
- 位置:《项目管理之美》第7章《撰写优秀的规格说明书》"良好的规格说明书能简化事情"一节(源文件:_epub-src/OEBPS/Text/part0062.xhtml)
- 结论依据:原文逐条列出撰写规格说明书的具体技巧:借用其他说明内容、避免行话、备有旧规格说明书、心中有特定读者、不要爱上Visio或流程图、区分参考资料与规格说明书、用伪代码描述复杂算法,并给出"花5分钟解释困惑并追问是否有更好说明方式"的具体做法,直接支撑本卡片结论。
- 原始内容:从其他规格说明书那里借用良好的说明内容