知识卡片
技术文档按接口写
技术规范的目标读者是没参与过这个项目、却要把它跑起来的人,所以写法应模仿接口文档。至少要交代四类信息:
- 输入:数据结构、字段类型、是否要求结构化、数值型还是字符型。
- 预处理:使用前需要做哪些转换,是否附了转换脚本。
- 输出:包含什么,需要何种再加工。例如模型给出的是流失概率,还要定阈值才能转成高风险账户名单。
- 异常:超出预期范围的数据、缺失值、空值、零、NA、格式或类型不符时,代码如何表现,对下游有什么影响。
此外要说明运行时性能与资源代价、与下游系统的集成方式、以及在哪些约束下才能满足约定的服务水平。阈值与训练算法最好留出可调整的余地,人工干预或自动学习都算。
即便文档齐全,工程师常会直接读代码,所以关键逻辑处必须有注释:怎么执行、逻辑为何如此、改动输入输出时要注意什么。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
- · 第12章 结尾
原书出处 · 1 处
- 第12章 结尾 · 查看原书依据
团队应该以类似应用编程接口(API)的方式为其代码编写技术文档。很多情况下,模型被封装为函数,在生产环境中读取一组输入,对数据进行可能的预处理,并创建包括一组处理后结果的输出。
参考来源
- 位置:《数据科学与大数据分析 数据的发现 分析 可视化与表示》第12章 结尾(源文件:extracted/数据科学与大数据分析 数据的发现 分析 可视化与表示/_epub-src/text/part0022_split_002.html)
- 结论依据:12.2.10 要求以类似 API 的方式为代码写技术文档,说明输入输出、数据转换、异常处理与性能约束,并强调代码注释的重要性。
- 原始内容:团队应该以类似应用编程接口(API)的方式为其代码编写技术文档。很多情况下,模型被封装为函数,在生产环境中读取一组输入,对数据进行可能的预处理,并创建包括一组处理后结果的输出。