项目说明文档编写规范-原创手记-慕课网

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 串，日期和作者。

$ git blame -L 160,+10 sha1_file.c

其中 -L 160,+10 用来限制显示的行数，详细参考 http://gitbook.liuhui998.com/index.html