怎么写项目细节实现文档？

[yurong333333]

背景：我司的文档都是写接口文档，没看见过什么技术细节实现文档。本人写 java 。

疑问：大佬们的公司有要求写项目功能的技术实现细节文档吗？有的话可以给个参考吗？实在是找不到类似的参考。

举例：一个 controller 层，里面的 service 层可能包含几个小方法，应该怎么去写清楚？目的就是想着怎么让别人看得明明白白。

补充：本人目前在写一些个人的项目，但是无项目细节实现文档的编写经验，特请教 V 站的大佬。有链接请直接甩，感谢感谢。

[yurong333333]

@blackshow 好滴，这就去看，感谢。

[corningsun]

描述 service 类有几个方法，一点意义都没有，而且这个不就是 java doc 的功能？

描述清楚关键业务的实现逻辑才是必要的，可以综合考虑用各类 UML 图，比如：架构图、时序图、状态图等。

[yurong333333]

@corningsun 前一句话觉得您可能没看清楚我表达的意思。但后一句话您又确实回答了问题。感谢。

[lidlesseye11]

可以写一些要点。比如
参数的要求
有什么全局变量（是否线程安全）
主要的处理逻辑（判断，循环）
是否用了比较复杂的数据结构
是否涉及多线程
是否有数据库等中间件的 crud
可能抛出哪些异常
打了哪些 log
有哪些监控

要写的详细的话，日企有个 review 流程叫塗り潰す
就是左手文档右手代码，文档里看一句涂掉一句，代码里涂掉相关的行。
最后 review 完，文档和代码全都是涂掉的，一句不多一句不少。
可以说是非常工匠精神了

[2NUT]

一楼的回复是有价值的，直接被你无效了

你说的那种是项目经理写的，不属于一般非技术经理程序员的职责范畴

[yurong333333]

@lidlesseye11 学习了，感谢您的回复。

[SteveWoo]

写文档的话，先想清楚写这个文档的目的（给谁看，对方的知识水平如何，读者需要提前具备哪些基础知识，期望对方看了能收获哪些内容），基于以上写好文档的背景和意义。

接下来就围绕目的，慢慢的撸了（除非用于技术评审，其不用纠结文笔，专业术语哪些玩意），能让具备前置条件的人看懂就行了。

[yurong333333]

@SteveWoo 主要是给那些完全没接触过该项目的人看，假设该读者的工作经验为一年及其以上，希望读者能够通过我的文档能够快速了解该项目的全局，并对该项目能够进行快速上手和二次开发。

[SteveWoo]

@yurong333333 解该项目的全局 和 二次开发 之间有点矛盾了。
快速上手和二次开发建议放弃文档介绍，工作了这些就要自己去啃代码，找人请教业务，不要主动去教。

建议重点写，全局概览，和你了解的业务流程。


1. 先介绍负责的块属于公司哪个产品线或者中台主要服务哪些，有什么价值。
2. 重点画个大图，介绍自己负责的那些模块接口，是做什么，相互是否关联，上下游游用户是谁，责任人是谁，有问题可以找谁。 这些都可以用方框+线条搞定了。
3. 其后，把自己熟悉的业务，业务流程介绍清楚，也可以用方框+线条，然后简单的说明涉及到哪些模块（这里不要写太详细，职业的打工人应该自己去啃，不需要保姆教学）