ONIModTutorial

Appearance

技术文档写作规范 ​

本规范用于保持教程的技术边界清楚、示例可验证，并减少版本更新后误导读者的风险。

内容结构 ​

每个技术页面尽量按以下顺序组织：

  1. 本页完成什么。
  2. 前置条件。
  3. 最小可运行示例。
  4. 代码说明。
  5. 如何确认生效。
  6. 常见错误。
  7. 当前版本注意事项。

一段只表达一个主要结论。先说明代码的用途，再展示代码；代码后解释关键 API 和验证方式。

区分结论类型 ​

  • 事实：由当前 DLL、游戏日志或官方文档直接确认。
  • 建议：通常更容易维护，但仍可能因目标方法和其他 Mod 而变化。
  • 经验：注明适用的游戏版本和测试环境。
  • 版本限制：放在页面顶部的验证信息和“当前版本注意事项”中。

不要把经验写成无条件规则。避免使用“绝对不会”“其他情况全部”“唯一正确”等表述，除非它是格式或 API 的硬性要求。

语言和标题 ​

  • 标题使用纯文本，Emoji 只放在 warning、info、tip 或 danger 提示框中。
  • 少量比喻可以帮助理解，但不要连续使用“手术、暴力、后门、天书、金法则”等夸张词汇。
  • 对初学者说明前置知识，不使用“不了解就不要继续”一类劝退语气。
  • 术语使用仓库中已经采用的 API 名称，并在首次出现时给出简短说明。

示例要求 ​

  • 可复制代码必须能针对当前支持的游戏 DLL 编译，或明确标注为伪代码。
  • 代码块中不要保留未经验证的旧 API。
  • 示例应说明输出目录、所需资源和最小验证步骤。
  • 版本敏感页面必须包含以下 frontmatter：
yaml
testedGameBuild: <具体 Build>
targetFramework: netstandard2.1
apiVersion: 2
lastVerified: YYYY-MM-DD

正文使用统一提示：

md
::: info 验证环境
本页示例已使用 Build XXXXX 对应的本机 Managed DLL 完成编译检查；尚未在游戏内完成运行验证。
:::