Scratch扩展文档完整性与易用性标准

一、评估维度概述

本标准专注于评估Scratch扩展的文档质量和积木块易用性，不涉及功能风险评分，主要包括以下四个核心维度：

评估维度： 积木块易用性 扩展文档完整性 文档易读性 内容准确性

每个维度分为四个评级：优秀、良好、可接受、不合格

二、积木块易用性标准

优秀

核心特征：
  • 积木命名简洁明确，符合Scratch用户习惯，一眼可理解功能用途
  • 积木分类逻辑清晰，功能相近的积木放在同一类别
  • 输入参数设计合理，有明确的类型提示（数字/文本/布尔值）
  • 包含恰当的默认值，减少用户配置负担
  • 积木图标与功能高度匹配，视觉识别性强
  • 复杂功能拆分为多个简单积木，易于组合使用
  • 有清晰的错误提示，帮助用户理解使用错误原因
示例：数学运算扩展中的"[数字1] 加 [数字2]"积木，有明确的数字输入框，默认值为0，图标使用"+"符号

良好

核心特征：
  • 大多数积木命名清晰，符合使用习惯
  • 积木分类合理，便于查找
  • 主要参数有明确的类型提示
  • 大部分积木有恰当的图标
  • 复杂功能有基本拆分，组合使用难度适中

可接受

核心特征：
  • 积木命名基本可理解，但部分术语较专业
  • 分类逻辑存在小问题，但不影响查找
  • 部分参数缺少明确的类型提示
  • 图标设计一般，部分与功能关联不紧密
  • 复杂功能拆分不足，需要查看文档才能正确组合

不合格

核心特征：
  • 积木命名模糊或使用专业术语，难以理解功能用途
  • 分类混乱，同类功能分散在不同类别
  • 参数类型不明确，用户无法判断应输入什么内容
  • 缺少图标或图标与功能无关
  • 复杂功能未拆分，单块积木参数过多（超过4个）
  • 错误提示模糊或缺失，用户无法排查问题
示例：仅命名为"处理数据"的积木，无图标，包含多个未标注类型的输入框，出错时仅显示"错误"而无具体原因

三、扩展文档完整性标准

优秀

核心特征：
  • 包含扩展完整介绍，说明用途和适用场景
  • 所有积木块都有详细说明，包括参数含义和返回值
  • 提供多个完整的使用案例，覆盖主要功能组合
  • 包含常见问题解答(FAQ)和 troubleshooting 指南
  • 提供积木块组合的最佳实践建议
  • 包含清晰的截图或动画演示操作过程
  • 提供版本更新日志和历史变更记录

良好

核心特征：
  • 包含扩展基本介绍和主要用途说明
  • 绝大多数积木块有说明，关键参数有解释
  • 提供1-2个基础使用案例
  • 包含常见问题的简要解答
  • 有基本的使用截图说明

可接受

核心特征：
  • 有简短的扩展介绍，说明基本功能
  • 主要积木块有简要说明，但部分参数解释缺失
  • 有简单的使用示例，但不完整
  • 缺乏FAQ，但有基本的联系支持方式

不合格

核心特征：
  • 无任何文档或仅有扩展名称
  • 积木块完全没有说明，用户只能猜测功能
  • 无任何使用案例或示例
  • 不提供任何支持信息或问题反馈渠道
  • 文档内容与扩展实际功能不符

四、文档易读性标准

优秀

核心特征：
  • 语言简洁明了，使用Scratch目标用户（儿童/初学者）易于理解的词汇
  • 结构清晰，使用标题、列表等格式组织内容，重点突出
  • 步骤说明详细但不冗余，逻辑连贯
  • 专业术语有明确解释，必要时提供例子
  • 图文结合，图片/截图清晰并配有说明
  • 使用短句和简单句式，避免复杂从句
  • 有目录或导航，方便快速查找内容

良好

核心特征：
  • 语言通俗易懂，大部分词汇适合目标用户
  • 结构合理，使用基本格式组织内容
  • 步骤说明清晰，逻辑顺畅
  • 主要专业术语有解释
  • 有必要的图片辅助说明

可接受

核心特征：
  • 语言基本可理解，但存在少量专业术语未解释
  • 结构一般，部分内容组织不够清晰
  • 步骤说明存在跳跃，但整体可跟随
  • 图片较少或质量一般，但不影响理解
  • 存在少量长句，但不影响整体理解

不合格

核心特征：
  • 大量使用专业术语且无解释，超出目标用户理解能力
  • 结构混乱，内容无序，难以跟随
  • 步骤说明模糊或缺失关键环节
  • 无图片或图片质量差，与内容无关
  • 存在大量语法错误或错别字，影响理解
  • 使用冗长复杂的句子结构

五、内容准确性标准

优秀

核心特征：
  • 文档内容与扩展实际功能完全一致
  • 无任何错误信息、错别字或语法问题
  • 示例代码/积木组合可直接运行，结果与描述一致
  • 参数范围、限制条件描述准确完整
  • 已知问题有明确说明，不隐瞒功能限制
  • 与最新版本扩展完全同步，无过时信息

良好

核心特征：
  • 文档内容与扩展功能基本一致，存在微小差异但不影响使用
  • 存在极少量错别字，但不影响理解
  • 示例基本可运行，可能需要微小调整
  • 主要参数范围和限制条件有准确描述
  • 大部分内容与当前版本同步

可接受

核心特征：
  • 文档内容与扩展功能有一些差异，但核心功能描述准确
  • 存在少量错别字和语法问题，但不影响整体理解
  • 示例需要调整才能运行，但有明确的修改方向
  • 主要参数的描述基本准确
  • 部分内容可能基于旧版本，但有版本说明

不合格

核心特征：
  • 文档内容与扩展实际功能严重不符
  • 存在大量错别字和语法错误，影响理解
  • 示例无法运行或运行结果与描述完全不符
  • 参数描述错误，可能导致用户误用
  • 隐瞒已知问题或功能限制
  • 文档内容基于旧版本，与当前版本差异巨大
示例：文档说明某积木"返回两个数字的和"，但实际功能是返回两个数字的乘积；提供的示例积木组合因参数错误无法运行

六、文档与易用性问题反馈模板

针对积木易用性问题

反馈内容：该扩展的[具体积木名称]存在易用性问题，[具体描述问题，如命名不清晰/参数类型不明确/缺少默认值]。建议[具体改进建议]，以提高用户体验。

针对文档完整性问题

反馈内容：该扩展文档不完整，缺少[具体缺失内容，如某积木的说明/使用示例/参数解释]。这些信息对用户理解和使用[具体功能]至关重要，建议补充完善。

针对文档易读性问题

反馈内容：该扩展文档存在易读性问题，[具体描述，如使用过多专业术语未解释/结构混乱/步骤说明不清晰]。建议[具体改进建议，如简化语言/增加目录/补充图示]以提高可读性。

针对内容准确性问题

反馈内容：该扩展文档存在准确性问题，[具体描述错误内容，如某积木功能说明与实际不符/示例无法运行/参数描述错误]。这可能导致用户误用，建议核实并修正相关内容。