[Meta] Style-guide

[3TUSK]

Synopsis / 简介

写作风格指南。

Description / 详细信息

一份说明”如何写 Sputnik 的“文档，覆盖措辞、语气等。

Justification / 理由

Harbinger 的普遍反馈是”不像是给新人看的“，但对 Harbinger 读者群的假定只有”了解 Java 编程语言“一条，所以现在（2020年2月28日）的 Harbinger 的写作风格肯定是有问题的。
为避免重蹈覆辙，有必要准备一份风格指南以供校读时参阅。

Remarks / 备注

是谁在给我挖坑？

[jihuayu]

在制作风格指南前，我们需要做这么几件事：

• 对 Sputnik 的目标群体进行画像。
• 对 Sputnik 的教学目的进行分析。

[3TUSK]

备忘：我们需要的东西是一群假想的用户模型（Peronsa, peronsae）。
这些用户模型的画风目前是这样的：

1. 能用 Java 写一些非常简单的小程序
2. 玩过一段时间 Minecraft
3. 英语水平跨度巨大
4. 没有计算机科学、软件工程等相关领域的背景

问题：

1. “非常简单的小程序”有没有定量的标准？
2. “玩过一段时间 Minecraft“是指玩过多久？
3. 要不要引入”有计算机科学、软件工程等相关领域背景“的用户模型？

[jihuayu]

我的想法是这样的，目标用户：

• 拥有C++/Java/C#或其他面向对象语言基础。
• 玩过一段时间 Minecraft 原版及模组，基本了解 Minecraft 的行为。
• 拥有借助翻译阅读注释的能力。
• 会用搜索引擎。

[SeraphJACK]

最后两条怕不是要求太高了（笑

[jihuayu]

这是我刚开始写模组的状态。
最后两个的确有点高，但是没办法，这肯定要。

[SeraphJACK]

idea：
每一章之前列出前置知识点，并分为上下两章：

• 上半章：抛弃细节，主要讲解概念以及大致流程
• 下半章：主要讲解细节，例如具体代码实现

相关联的几章之后在适当的地方插入运用以上知识点的具体实例，让读者加深理解

---

目前和 SF 讨论后列出的大致 SUMMARY：

- 入口
- 事件
-- example 打印一个 hello world

- GameObject Item Itemstack Block Blockstate Entity EntityLiving
- ForgeRegistry
- Item
- Block
- 数据存储
- Advanced Item
- TileEntity
-- example item/block
- Liquid
-- example liquid
- Entity
-- example

- 物理/逻辑 服务端/客户端
- 网络 IO
- Capability
-- example

- Command
-- example

- Recipe
-- example
- Advancement
-- example

渲染相关
- 贴图 模型 JSON Models
- GUI
- TESR TEISR
- 实体渲染

- 本地化、国际化

- 配置文件

注：读者不一定是按照顺序阅读教程的，不需要讨论 “为什么配置文件放在这么后面”这类的问题。知识点的结构是树状的，而教程所展示的则是线性的，无论怎么调整都会有类似的问题，我认为只需要告诉读者不需要按照顺序阅读，并且在每一章标记前置知识就不会有问题。

---

抄送 @switefaster

[jihuayu]

好，我可以先写初稿，然后其他人再来修正。

[3TUSK]

备忘：
就「知识点的结构是树状的，而教程所展示的则是线性的，无论怎么调整都会有类似的问题」这个问题，可能的解决方案有：

1. 既然整个知识网络是树，那后序遍历（Post-order Traversal）一遍即可。这里我们假定子节点是前置知识点，且根节点是这个教程的最终目标。
2. “我认为只需要告诉读者不需要按照顺序阅读，并且在每一章标记前置知识就不会有问题。”
3. 直接把教程目录做成树状的。
4. 未曾设想的道路：教程目录不再是树，而是森林，aka 有多个根结点的有向无环图。

---

备忘 II：
第一章需要讲清楚的概念，无特定顺序：

• 服务器 vs 客户端的概念，参考各种各样的网游和其他单机游戏，又名“你为什么不能在客户端上处理游戏逻辑”，see also Model-View-Controller
• Gradle，以及为什么要用 Gradle，又名“不用 Gradle 的话你的开发之旅会变成什么鬼样子”
• 映射表，以及为什么要有映射表，又名“为什么我们要费这么大力气把名字三天两头换来换去”
• 我们多数时候都是在使用 Minecraft 本体，中间不隔着 Forge
• Forge 的两个部分：兼容层和 Mod加载器

[SeraphJACK]

只要是线性的，无论怎么调整都会有 “为什么xxx放在这么后面”这类问题，这不是遍历能解决的。 此外，后序遍历的是二叉树，而知识点并不一定是一颗二叉树。 发自我的 iPad 在 2020年3月27日，01:25，Urey. Xue <notifications@github.com<mailto:notifications@github.com>> 写道： 备忘： 就「知识点的结构是树状的，而教程所展示的则是线性的，无论怎么调整都会有类似的问题」这个问题，可能的解决方案有： 1. 既然整个知识网络是树，那后序遍历（Post-order Traversal）一遍即可。这里我们假定子节点是前置知识点，且根节点是这个教程的最终目标。 2. “我认为只需要告诉读者不需要按照顺序阅读，并且在每一章标记前置知识就不会有问题。” 3. 直接把教程目录做成树状的。 4. 未曾设想的道路：教程目录不再是树，而是森林，aka 有多个根结点的有向无环图。

…

________________________________ 备忘 II： 第一章需要讲清楚的概念，无特定顺序： * 服务器 vs 客户端的概念，参考各种各样的网游和其他单机游戏，又名“你为什么不能在客户端上处理游戏逻辑”，see also Model-View-Controller * Gradle，以及为什么要用 Gradle，又名“不用 Gradle 的话你的开发之旅会变成什么鬼样子” * 映射表，以及为什么要有映射表，又名“为什么我们要费这么大力气把名字三天两头换来换去” * 我们多数时候都是在使用 Minecraft 本体，中间不隔着 Forge * Forge 的两个部分：兼容层和 Mod加载器

[SeraphJACK]

看起来我们需要把 入口 和 事件 这两章的顺序对调一下 @3TUSK @jihuayu @switefaster

[3TUSK]

把 入口 和 事件 这两章的顺序对调一下

579aea0 我迟到了……