Skip to content

教程编写规范

Jump to bottom
Samit edited this page Jan 17, 2023 · 4 revisions

Principles & Guidelines

内容结构安排

整个教程结构，应由浅入深，从低阶教程到高阶教程，并覆盖代码的各个特性和功能的教学。建议包含信息：

- 如何安装
- 快速上手
- 模型训练
   a. 视觉分类模型训练
   b. 模型微调(迁移学习)
   c. 预训练策略与Yaml配置参数列表
   d. 模型调试和精度问题定位
- 模型推理
   a. 基于Python推理
   b. 服务化部署
   c. 端侧部署
- 自定义新数据集
- 自定义新模型

手把手教学

假设用户零基础。在编写一个教程时，应当假设用户是直接点进来的，没有看过仓内其他的代码或文档。因此，在内容上，应当

  • 说明教程所用到的数据和其他文件的下载方式，并以命令行形式给出, 如wget https://path/to/src
  • 说明教程所用到的依赖包，以命令行形式给出。如 !pip install xx_package
  • 调用套件的关键接口时，可给出说明，并导航到APIs.

100% Runnable

确保用户下载notebook后，能在本地跑通。为此，应注意：

  • 避免使用绝对路径。
  • 注意本地环境的依赖包。
  • 最后restart Jupyter Notebook, 并检查能否一键运行通过。

格式规范

  1. markdown中引用函数名、变量名统一高亮，即func_name。
  2. 代码块应正确注明python或shell或text。

python代码块示例

import mindspore as ms

a = ms.Tensor(5)

shell代码块示例

cd ./data

text块示例

1. 打开网页
2. 选择

更详细的格式和风格规范请参考：https://github.com/google/styleguide/blob/gh-pages/docguide/style.md

Clone this wiki locally