執筆: トピックの執筆と編集

書く前に

スタイル規則と、リポジトリ直下のspec/conventions.mdを読みます。
リポジトリ直下のspec/structure.mdで、トピックがどこに収まり、どの番号になるかを確認します。

新しいトピックを書く

部と、その部で次に空いている小数番号を選びます。番号は連続しているので、新しいトピックは通常、その部の最後のトピックの次の番号になります。
トピックテンプレートからlocales/en-gb-oxendict/topics/PP-CC-slug.md (ゼロ埋めでダッシュ区切りの接頭辞、例えば02-01-...)を作成します。オックスフォード綴りで書き (spec/oxford-spelling.md参照)、他の3つのロケールは決して直接編集しません。
テンプレートに沿って書きます。内容トピックには、すべてのセクションが必要です。概要、重要な原則、推奨事項、トレードオフ(表付き)、ディスカッションの問い、セクター別の視点(スタートアップ、小規模事業、大企業、政府)、例(企業1つと政府1つ)、ビジネスケース、アンチパターン、5段階の成熟度モデル、ディスカッションのアイデア、重要な要点、参考文献です。
操作の経路を名指しします。どの指標ファミリーにも、「チームは測っているものを改善せずにこの数字を良く見せるにはどうするか、そしてどのガードレールがそれを捕まえるか」への明示的な答えが必要です(トピック1.2参照)。
用語は初出時に定義します。重要な概念には、初出時にWikipediaのリンクを加えます。本文中のみです。
関連するトピックを小数番号で相互参照します。例えば「(トピック2.1)」。
トピックをspec/structure.mdに追加します。
部の導入(N.0)がそのトピックを列挙している場合は、そこに箇条書きを追加します。
python3 tools/localize.pyを実行して、トピックをen-001、en-gb、en-usに派生させます。
just navを実行し、続いてjust testを実行します。

既存のトピックを編集する

セクションの順序と見出しはそのままにします。テストは、内容トピックが必要なセクションをすべて備えているかを確認します。
編集がそれらを対象としていない限り、インライン定義、Wikipediaリンク、表、参考文献リストは保ちます。
エムダッシュや禁止フレーズを持ち込まないでください。言い換える場合は、ダッシュを入れるのではなく、書き直します。
その後、編集したen-gb-oxendictの原典からen-001、en-gb、en-usを派生し直すため、python3 tools/localize.pyを実行します。

名称変更または番号振り直し

locales/en-gb-oxendict/でファイル名を変更し、# N.M Title見出しを更新し、spec/structure.mdを更新し、古い番号を指すすべての相互参照を更新します。
他の3つのロケールでもファイル名を変更するため、python3 tools/localize.pyを実行します(同じ相対パスから4つすべてを派生させます)。
just navとjust testを実行します。テストは、H1とファイル名の不一致、番号の抜け、原典からずれたロケール、壊れたリンクを指摘します。

口調のリマインダー

読者の成功を願う経験豊富な同僚のように書いてください。温かく、平易で、率直で、役に立つ。短い文。埋め草なし。