[后端] 如何写好开发/设计文档？

[ryalu]

本人已从事后端开发工作五六年了，在 AI （ Cursor..） 的辅助下，日常的代码开发、性能优化也算是能够得心应手了。

现在愈发觉得能否写好设计、对接文档才是展示个人能力的关键因素了，想听听大家对写好设计文档的看法和经验，包括但不限于好的文档结构和风格，流程图、时序图等开发经验、工具....

也欢迎分享一些优秀的设计文档。

分享下个人之前收藏的《 Google 技术写作》

[sakurawzt]

实际情况是，你写好了，前端不看，非要问你，还不如给他截图呢，哎。

[litchinn]

按照那些写的好的文档写啊当然是

[kk2syc]

文档？那不是离职交接那个月才干的活吗？

[youyouzi]

别给自己加太多戏，前端根本不看的。。。你要是给领导看另说

[chendy]

一样，问问 AI 就行
然后你就会发现文档写出花也没卵用，不看的还不看，看不懂的还是看不懂，会找你问的还是会找你问

[ryalu]

@youyouzi #4 现在整天就是需求对接会、评审会，写不好都不知道讲啥..

[ryalu]

@chendy #5 AI 生成的不太行，他无法完全理解具体的业务场景，还是得自己根据框架和实际的业务场景来写。写出花了领导眼睛一亮，涨薪不就来了吗

[zoharSoul]

随便写写拉倒

[youyouzi]

@ryalu #6 为了应付开会，那就需求拆分，对每个需求点画泳道图，拆解功能点，写伪代码，写接口 api 路由，表结构，数据库字段，这种会应该每个人上去讲一讲，你写个 10 分钟内讲完的就行啊。

[Betsy]

https://arc42.org/overview
这里给了模板和样例

https://zh-style-guide.readthedocs.io/zh-cn/latest/
这里给了写作风格指南

两个结合起来就是一篇合格的设计文档了

[Betsy]

@Betsy 能把设计文档写清楚的人还是很厉害的，
能写他人之所想，想他人之未想；
知道哪些该写，哪些不该写（可能在评审的时候能被喷死）；
能准确表达自己的思想，准确向干系人传递设计方案

从经验来看，这个能做好的人，工程能力不会太差

[bxb100]

依照 2 年前我在 v 站的讨论, OpenAPI spec 先行的理论做法被一致批评

[qianji201712]

文档也让 cursor 来写就好了，不过前提是你后端代码清晰，设计比较好

[Plutooo]

写完代码以后再用大模型逆推文档不应该更容易吗

[Granado]

我理解设计文档写好是必要的，也是基本的。要老板眼前一亮还是得有全局视角的规划，不限于业务规划、技术规划或者有明显的技术革新方案能提效降本。

[layxy]

只要后端开发完了文档就出来了(使用 ai 或者 swagger),不过这就涉及到一个争论点,先有文档还是先有接口?

[NMmmm]

学学优秀的三方 SDK 怎么写文档的不就好了

[xiaohusky]

这个不算绩效啊，有什么用吗