“代码越少,错误就越少,”Ruby的发明者Matz说。文档越短,包含的错误越少,越容易阅读,越容易更新,越有可能带来简洁的设计。简而言之,缩短时间有太多的好处。对于产品团队来说,简短的文档更容易编写,因此这一原则不是负担。
在刚入行做产品时,我发现一个非常奇怪的现象:在我们开完需求会议把产品大概的需求告诉研发设计人员后,他们在实际功能代码开发过程中很少去看需求文档。通常是遇到问题口头询问。我当时就很奇怪,产品需求文档里每一个步骤和功能点都写得很细,为什么他们从来都不喜欢读我写的文档?
于是我带着疑问和研发沟通,得到的答案是:他们没时间看我写的过于冗长的文档。他们只需要简单地理解这个功能大概是做什么的,怎么去实现它即可。
文档中的内容又多又复杂,要把文档完全理解非常费时,一些不影响开发的字段完全可以放在备注中。从这件事之后,我开始反思研究自己平时写文档的问题。以前总担心研发的程序员们看不懂,习惯性的会去把一个需求写得非常细。复杂的一个功能可能写到十几行(一不留神就接近500多个字)。
在研发同事的角度来看,在较短的开发时间里想用最快的速度去理解需求,长篇幅的文档确实增加了他们理解上的门槛难度以及阅读内容的速度。在梳理需求文档时,保持文档简短,会增加整个文档的易读性。下面是我总结有关保障文档简短的3个步法。
1) 分析需求:开发中需要执行哪些操作。
2) 填写主干:画出主要操作流程。
3) 添加枝叶:显示详细信息。减少文档重量不仅可以提高可读性,还可以增加灵活性。
因为在开发过程中,您会发现很难在最终开发的产品和原始的书面需求文档之间保持完全的一致性。由于接口提供、技术等方面的问题,在开发过程中需求会或多或少地发生变化。通过简短地编写文档,还可以帮助修改以后的需求变更。
领取专属 10元无门槛券
私享最新 技术干货