68 lines
3.4 KiB
Markdown
68 lines
3.4 KiB
Markdown
# 撰写总则
|
||
|
||
## 目录
|
||
|
||
- [文档分三类](#文档分三类)
|
||
- [每篇文档都写目录](#每篇文档都写目录)
|
||
- [图中只用项目词条](#图中只用项目词条)
|
||
- [图只画本层](#图只画本层)
|
||
- [功能模块何时拆开](#功能模块何时拆开)
|
||
- [文件名](#文件名)
|
||
- [示例与正式文档](#示例与正式文档)
|
||
|
||
## 文档分三类
|
||
|
||
|
||
| 文档 | 位置 | 正文 |
|
||
| ---- | ---------------------------------- | ---------------------------------------- |
|
||
| 项目架构 | `doc/项目架构.md`，全库一篇 | 目录结构（到 `features/[feature]`）、模块定义、功能模块之间的业务数据流 |
|
||
| 基础应用 | `doc/基础应用/`，`src/app` 下，一个目录一篇 | 功能定义、使用示例、该应用内部的数据流与时序 |
|
||
| 功能模块 | `doc/功能模块/`，`src/features` 下一个目录一组 | 模块内目录、功能定义、核心业务层与核心模型、核心业务时序图 |
|
||
|
||
|
||
`src/app` 下的每个目录是一个基础应用。`src/features` 下的每个目录是一个功能模块。
|
||
|
||
章节的写法分别见：
|
||
|
||
- [项目架构文档撰写说明](./项目架构文档撰写说明.md)
|
||
- [基础应用文档撰写说明](./基础应用/基础应用文档撰写说明.md)
|
||
- [功能模块文档撰写说明](./功能模块/功能模块文档撰写说明.md)
|
||
|
||
## 每篇文档都写目录
|
||
|
||
标题下第一段是目录，标题为「目录」。条目与正文标题一致，并链到对应标题。拆出去的业务文档写进父文档目录，链到文件。
|
||
|
||
撰写说明、示例、正式文档都要有目录。
|
||
|
||
## 图中只用项目词条
|
||
|
||
Mermaid 的节点、参与者、箭头文字只用仓库里的目录名、类名、方法名、字段名。中文说明写在图外的正文里。
|
||
|
||
## 图只画本层
|
||
|
||
项目架构只画 `home`、`security`、`project`、`editor` 之间的业务数据。不画 `session`、`network`、`db`、`routes` 这些基础应用，也不画时序。
|
||
|
||
基础应用只画该目录内部的类和函数。不画功能模块的调用链，也不把其他基础应用的内部步骤画进来。调用方可以出现在使用示例的代码里。时序图已经能说明这条行为时，不再画数据流图。
|
||
|
||
功能模块的时序写在功能模块文档。那里不展开基础应用内部步骤。
|
||
|
||
## 功能模块何时拆开
|
||
|
||
一条主业务时，时序图写在该模块主文档里。
|
||
|
||
同一模块有多条要分开讲述的事件业务时，为每条业务另写一篇，放在该模块目录下。主文档保留目录结构、功能定义、核心业务层与核心模型，并用目录链到各业务文档。编辑器的打开、绘制、撤销与重做按这个方式拆开。
|
||
|
||
方法定义写在主文档的核心业务层。业务文档写该业务的定义和时序图，并点名用到的方法。
|
||
|
||
## 文件名
|
||
|
||
- 基础应用：`中文名(目录名).md`，例如 `会话(session).md`。
|
||
- 功能模块主文档：`模块名(目录名).md`，例如 `编辑器模块(editor).md`。
|
||
- 拆出的业务文档：放在同一模块目录，用业务名作文件名，例如 `绘制.md`。
|
||
- 说明与示例只放在 `doc/文档撰写说明与示例/`。
|
||
|
||
|
||
|
||
## 示例与正式文档
|
||
|
||
示例用来对齐章节和粒度，正式文档另写。类名、方法、目录以当时仓库为准；代码变了就改正式文档。 |