写作:撰写和编辑主题

动笔之前

  • 阅读风格规则和仓库根目录的 spec/conventions.md。
  • 查看仓库根目录的 spec/structure.md,了解这个主题适合放在哪里,应该用哪个编号。

撰写新主题

  1. 选择部分,以及该部分中下一个空闲的小数编号。编号是连续的,因此新主题通常取其所在部分最后一个主题之后的编号。
  2. 从主题模板创建 locales/en-gb-oxendict/topics/PP-CC-slug.md(补零并以连字符分隔的前缀,例如 02-01-...)。 用牛津拼写书写(参见 spec/oxford-spelling.md);绝不直接编辑其他三个语言区域。
  3. 按模板书写。内容主题需要所有部分:概述、关键原则、建议、权衡(带表格)、讨论问题、 行业视角(初创公司、小企业、大型企业、政府)、示例(一个企业的,一个政府的)、商业论证、反模式、五级成熟度模型、 讨论想法、关键要点和参考文献。
  4. 点明操纵路径。每个指标家族都需要对“团队如何在不改善其所衡量之物的情况下让这个数字好看,以及哪道护栏能抓住它”给出明确回答(参见主题 1.2)。
  5. 术语在首次使用时给出定义。关键概念在首次提及时添加维基百科链接,仅限正文。
  6. 用小数编号交叉引用相关主题,例如“(主题 2.1)”。
  7. 把主题添加到 spec/structure.md。
  8. 如果部分导言(N.0)列出了其主题,请添加一个条目。
  9. 运行 python3 tools/localize.py,把主题派生到 en-001、en-gb 和 en-us。
  10. 运行 just nav,然后运行 just test。

编辑现有主题

  • 保留各部分的顺序和标题。测试会检查内容主题是否仍有每个必需的部分。
  • 保留行内定义、维基百科链接、表格和参考文献列表,除非编辑本身就是针对它们的。
  • 不要引入长破折号或被禁用的措辞。如果要改写,请重写,而不是插入一个破折号。
  • 之后运行 python3 tools/localize.py,从编辑后的 en-gb-oxendict 源头重新派生 en-001、en-gb 和 en-us。

重命名或重新编号

  • 在 locales/en-gb-oxendict/ 中重命名文件,更新 # N.M Title 标题,更新 spec/structure.md,并更新每一处指向旧编号的交叉引用。
  • 运行 python3 tools/localize.py,同时重命名其他三个语言区域中的文件(它从同一个相对路径派生全部四个)。
  • 运行 just nav 和 just test。测试会标出 H1 与文件名不匹配、编号缺口、偏离源头的语言区域,或损坏的链接。

语气提醒

像一位希望读者成功的资深同事那样写。温暖、朴素、直接、有用。句子要短。不要填充。