首页手记项目说明文档编写规范

项目说明文档编写规范

标签：

设计模式 Git

Markdown 的使用可以按需要参考：

Markdown的简单用法
vscode的一个插件的使用手册 Markdown Preview Enhanced 详细介绍了Markdown 的语法以及周边
数学公式 Markdown公式编辑学习笔记
画流程图：Mermaid 学习

规范1：使用 Markdown 编写说明文档

为了更好的利用 Git 管理项目，一定要使用 Markdown 来编写项目说明文档，而不是使用 .docx 等格式的文件编写项目说明文档（Git 无法管理细节）。不要使用 .txt 用来管理项目说明文档，它的功能太单一，同时可能会引入一些编码错误问题，而相对的 Markdown 功能可以满足大多数项目开发的需求，支持图片，网址，以及音频的插入，并且也可以导入流程图。Markdown 的语法并不复杂，很容易上手，支持将其转换为 pdf、docx 等格式文档。Markdown 可以直接作为幻灯片进行展示。

规范2：按照目录树编写说明文档

为了更好地模块化管理项目，不推荐仅仅使用一个目录用来存放项目，应该将项目按照模块或者功能分割为不同目录。这些目录形成了具有等级的目录树，为了项目的清晰，最好在每个目录下均存放一个 README.md 文件用来记录该目录的功能与修改记录（重大修改）。

规范3：单个 `README.md` 文件的编写规范

在文档中简略介绍该目录做了什么（What），为什么这样做（Why），怎么做的（How）。
在项目根目录的 README.md 需要交代涉及版权问题的一些内容。
引入 hotfix.md，并将重大修改编写进 README.md。

规范4：`hotfix.md` 文件的编写规范

项目并不是一天建成的，需要在 hotfix.md 文件中记录项目开发过程中出现的问题与解决策略。下面是一个例子：

# teacher helper 版本更新记录

抠图辅助软件工具：teacher helper

## v0.2

1. 修复 v0.1 版本的中文路径输出显示乱码问题。（v0.2.1@xinet:2019/7/26）
2. 修复 代码部分逻辑问题。（v0.2.2@xinet:2019/7/27）

## v1.0（v1.0.1@xinet:2019/8/5）

- 将 `检查` 按钮改为 `审查`，输出的 `errors.txt` 更名为 `checkout.txt`；
- 重构了代码的逻辑，提高代码的容错能力；
- 增加对 负样本 的搜索功能。

v0.2.2@xinet:2019/7/27中 v0.2.2 表示版本号，xinet 表示责任者，2019/7/27 表示修改的时间。

更多与项目开发相关的内容参考：xinetzone/projects

小 Tips：

如果你要查看文件的每个部分是谁修改的，那么 git blame 就是不二选择. 只要运行 git blame [filename]，你就会得到整个文件的每一行的详细修改信息：包括 SHA 串，日期和作者。