作者wt (Time to Change!)
看板Soft_Job
标题Re: [请益] 怎样的文件才算好？
时间Thu Oct 4 21:39:18 2018
可以从几个角度去思考
1. 给谁看
工程师、PM、PR、业主。需要的资讯程度不同。
给同部门或者跨部门的工程师看，需要的资讯程度也不同。要考虑读者背景差异。
2. 文件预计达成的目的为何
读者可以从文件中找到或学会甚麽?
或是为了符合某些规定 CMMI
3. 文件更新频率
文件内容最好不要跟实际落差太大。
太细或者有可能变更的资讯，就要考虑一下做法。
例如code level的资讯都用注解为主，再用工具把注解捞出来自动编成文件。
举例来说：技术文件
对象：部门内後来加入的新人
目的：了解程式架构，方便新人快速上手。
对象：不同部门的工程师
目的：了解如何使用这套Lib/API
上面这个定位跟对象搞清楚，网路上就有很多文件范本可以参考。
※ 引述《jonjes (HONOKA)》之铭言：
: 最近写文件、架构或画流程图的机会变多了
: 虽然同事说只要找个专案外的第三者来看，对方能懂就好了
: 但还是很犹豫文件到底要定义到多细才好？
: 像func name 、func用途、参数、该参数的用途等
: 一般还会加个後续处理要做什麽吗
: （感觉这比较像是需求文件、而不是技术文件该加的）
--
※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 118.169.209.30
※ 文章网址: https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1538660362.A.248.html
1F：推 content71: 说的很好 10/04 22:28
2F：推 Ghamu: 最低标准 能让未来的自己看懂 10/05 00:06
3F：→ viper9709: 推楼上 10/05 00:14
4F：推 TAKADO: 推2楼 10/05 23:56
5F：→ meowyih: 据统计，九成以上的程式说明文件最後都只有自己会看XD 10/06 12:35