スタイル規則(共有、強制可能)

ハウススタイルを1か所にまとめたものです。「(test)」と記された項目はtests/validate.pyが強制し、違反するとビルドが失敗します。 完全な叙述版はリポジトリ直下のspec/conventions.mdです。

厳格なルール

• エムダッシュは使わない。 「—」(U+2014)は決して使いません。カンマ、コロン、括弧、または2つの文を使います。 エンダッシュ「–」は、1–9や2.1–2.8のような数値範囲でのみ許されます。(test)
• 決まり文句は使わない。 「not only … but also」、「but also」、「load-bearing」は使いません。「It’s important to note」、 「In today’s fast-paced world」、「It’s crucial to consider」、「It appears that」、「One could argue」、 「it’s not just X, it’s Y」の型は避けます。(test、最初の3つについて)
• 用語は初出時に定義する。 各トピックで初めて使うときに、略語を展開し、専門用語を定義します。例えば「mean time to recovery (MTTR)」。
• 重要な概念は初出時にWikipediaへリンクする。 トピックごとに1回、本文中のみ。形式: [term](https://en.wikipedia.org/wiki/Article_Title)。見出し、表、コード、参考文献セクションでは決してしません。(リンクの形式はtest)
• 実在する参考文献のみ。 実在する著作の著者とタイトル。捏造したタイトル、著者、URLは使いません。
• 操作の経路を名指しする。 指標ファミリーのトピックは、指標がどう操作されるか、どのガードレールがそれを捕まえるかを述べます(トピック1.2)。

文体

• 温かく、率直で、励ます。読者には「あなた」と呼びかけます。短い文、平易な言葉。要点から書き始めます。
• 意見がはっきりしていて実践的。ベンダー中立。製品名は事実としての例としてのみ挙げます。

構造(test)

• 内容トピックは、chapter-template.mdのセクション順をそのまま使います。
• 最初の見出しは# N.M Title(ドット付きのトピック番号)で、ファイルのゼロ埋めPP-CC接頭辞と一致します。
• 各部の中の番号は連続し、N.0から始まります。

編集後

• トピックの集合を変えた場合は、spec/structure.mdを更新してjust navを実行します。
• 常にjust testを実行します。