写作:撰写和编辑主题
动笔之前
- 阅读风格规则和仓库根目录的
spec/conventions.md。 - 查看仓库根目录的
spec/structure.md,了解这个主题适合放在哪里,应该用哪个编号。
撰写新主题
- 选择部分,以及该部分中下一个空闲的小数编号。编号是连续的,因此新主题通常取其所在部分最后一个主题之后的编号。
- 从主题模板创建
locales/en-gb-oxendict/topics/PP-CC-slug.md(补零并以连字符分隔的前缀,例如02-01-...)。 用牛津拼写书写(参见spec/oxford-spelling.md);绝不直接编辑其他三个语言区域。 - 按模板书写。内容主题需要所有部分:概述、关键原则、建议、权衡(带表格)、讨论问题、 行业视角(初创公司、小企业、大型企业、政府)、示例(一个企业的,一个政府的)、商业论证、反模式、五级成熟度模型、 讨论想法、关键要点和参考文献。
- 点明操纵路径。每个指标家族都需要对“团队如何在不改善其所衡量之物的情况下让这个数字好看,以及哪道护栏能抓住它”给出明确回答(参见主题 1.2)。
- 术语在首次使用时给出定义。关键概念在首次提及时添加维基百科链接,仅限正文。
- 用小数编号交叉引用相关主题,例如“(主题 2.1)”。
- 把主题添加到
spec/structure.md。 - 如果部分导言(N.0)列出了其主题,请添加一个条目。
- 运行
python3 tools/localize.py,把主题派生到en-001、en-gb和en-us。 - 运行
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 与文件名不匹配、编号缺口、偏离源头的语言区域,或损坏的链接。
语气提醒
像一位希望读者成功的资深同事那样写。温暖、朴素、直接、有用。句子要短。不要填充。