ドキュメントスタイルガイド

このガイドは EmDash ドキュメントの書き方を定義します。コントリビューションはこれに合わせて編集されます。暗記する必要はありません — レビュアーとエディターが助けます — しかし従うことでコントリビューションのマージが早くなります。

ドキュメントは、誰かが何かを行い、プロジェクトに戻るのを助けるために存在します。疲れている、急いでいる、第二言語で読んでいる、またはスタックに不慣れな読者に向けて書いてください。何よりもその読者に奉仕してください。

読みやすさ

以下を優先してください：

短い文と短い段落。
専門用語よりも平易な語彙。
略語と頭字語は初出時にフルスペル。
長い文章を分割するための見出しとリスト。
能動態。

EmDash でどう構築するかを文書化し、EmDash がどう構築されているかは文書化しないでください。実装の詳細は、読者が下す必要のある決定を変える場合にのみドキュメントに含めます（デフォルト以外の値を選ぶべきタイミング、プロジェクトに影響する注意事項）。使用例の代わりにはなりません。

EmDash 以外のトピック — TypeScript、AT Protocol、Web フォント、SQL — については、説明する代わりに信頼できるソースにリンクしてください。EmDash で機能を使うために知る必要があることを文書化してください。

何を強調するか

ページの強調は、読者がタスクを行うために必要なことによって設定されなければならず、EmDash を構築した人々にとって興味深かったり最近だったりしたことによってではありません。積極的に抵抗すべき 3 つの習慣：

執筆の新しさの重み付け。 決定が新しい、あるいは書き手の心に新鮮であることは、それを特集する理由にはなりません。最も変更されたものは、読者にとって最も重要なものであることはまれです。セクション、リスト項目、見出しを、読者がそれらを必要とする頻度で並べ、追加された時期ではなく。何かが変わったばかりだから文書化しているなら、おそらくドキュメントではなくチェンジログのエントリを書いています。
読者の関連性より構築者の関連性。 作成することが重要だった内部アーキテクチャと設計決定は、使用するには通常不可視で無関係です。読者が得る機能を述べ、その背後のメカニズムは述べないでください。コレクションを定義する読者は、パーサーの言語を知る必要がないのと同じように、スキーマがどこに保存されているか知る必要はありません。メカニズムが EmDash で作業している人を本当に助けるなら、ユーザー向けページではなく内部ドキュメントに属します。
藁人形的な自己定義。 EmDash を他のツールのカリカチュアとの対比で定義しないでください（「ほとんどの CMS とは異なり…」、「従来の CMS は…を強制する」、「多くの CMS ではコードで X を宣言する」）。EmDash が何をするかを直接述べ、それ自体で立たせてください。比較は、比較が読者自身の質問である場合にのみ許可されます：評価ページと「…から来た」オリエンテーションページで。そこでも具体的で公正でなければなりません — 具体的な動作とトレードオフであり、読者が嫌うよう誘われる藁人形ではありません。
否定による定義。 能力を_しなくてよい_仕事として枠づけること — 「書くマイグレーションがない」、「リビルドなし」、「コードに触れずに」、「別サービスなし」 — は偽装された藁人形です：あなたが発明した代替案を背負っている読者にしか通じません。読者が_何をするか_と_何が起こるか_を述べてください。「管理パネルでフィールドを追加する。すぐに反映される」 — 「マイグレーションなし、リビルドなし、コードなしでフィールドを追加する」ではありません。例外は、肯定的に述べられた具体的で読者に関連する動作です：「コンテンツはランタイムで提供されるため、編集はすぐに表示される」は EmDash についての事実です。「リビルドは不要」は、他の誰かの不在の苦痛として表現された同じ事実です — 前者を優先してください。

任意の文のテスト：タスクを完了しようとしている読者が、削除された場合に不利になるか？そうでなければ、削除してください。EmDash を他のものと比較している読者にしか意味がないなら、場所が間違っているか、カットすべきです。

常緑、チェンジログではなく

ユーザー向けページは、以前のバージョンが頭にない読者に向けて、EmDash が今どう機能するかを説明します。「今は」「もはや〜ない」「以前は」「古いものの代わりに」「これは変わった」はありません。バージョン間の違いはアップグレードガイドにのみ存在します。概念が最近導入されたことは、それが最近であると言及する理由にはなりません。

声とトーン

中立的で事実に基づく文を書いてください。事実を直接述べてください。

✅ プラグインは分離されたランタイムで実行され、宣言した API にのみアクセスできます。

❌ プラグインは何も悪いことが起こらない居心地の良い小さなサンドボックスに住んでいます！

私たち、我々の、_〜しましょう_は使わないでください。あなたは読者と一緒にいません。読者に直接語りかけるか、システムを説明するように言い換えてください。
_私_は決して使わないでください。 ドキュメントは著者についてではありません。
必要に応じて読者を_あなた_と呼んでください。特に何かがうまくいかない可能性があるステップを示す場合。
ナレーションやストーリーを語らないでください。 「X を設定したので、Y に進みましょう」はありません。セクションは目標から始め、次にステップです。
奇抜さ、マスコット、文化的参照は避けてください。 読む労力が増え、翻訳できません。
感嘆符はまれです。 本当に励みになるか驚くべきことにのみ使ってください。迷ったらピリオドを使ってください。

見出し

ページタイトルは <h1> です（フロントマター title から）。セクションは <h2> から始まります。
見出しは短く保ってください。<h2> と <h3> は「このページについて」サイドバーに表示されます。プレビューして折り返すものは短くしてください。
コロンを含む末尾の句読点はありません。
見出し内のコードは本文と同じように <code> でフォーマットしてください。

順序が重要でない場合、オプションやプロパティのセットなどには箇条書きリストを使用してください。
順番に従う必要があるステップには番号付きリストを使用してください。手順には Starlight の <Steps> コンポーネントを使用してください。
リスト項目が複数の段落に成長したり、複数のコード用語を含む場合は、代わりに <h3> セクションに切り替えてください。

例

「たとえば」は単一の例や仮定を導入します。
括弧内の「例：」は網羅的でないリストを導入します（例：GitHub、GitLab）。
すべてのオプションをカバーするリストは例のリストではありません — 「例：」なしで括弧を使ってください（必須プロパティ (src, alt)）。

スクリーンショット

スクリーンショットは、空間的関係、インターフェースの状態、またはコントロールの位置を実質的に明確にする場合にのみ使用してください。ページが画像なしで使用可能であるように、指示やその他の重要な情報はテキストに保ってください。

すべてのスクリーンショットは最新で、ページの特定の目的のためにキャプチャされている必要があります。関連する画面と状態を説明する代替テキストを提供してください。別のコントリビューターがキャプチャを再現できるように、フィクスチャ、ルート、ビューポート、ロケール、テーマを記録してください。

コードサンプル

コードサンプルは周囲の散文と同じくらい重要です。

すべてのコードブロックを、ブロックが何をするかを読者に伝える完全な独立した文で独自の行に導入してください。コロンで終わる文の断片、裸の見出し、または「以下のように：」で導入しないでください。

✅ 次の例は sandboxed 配列にプラグインを登録します：

❌ プラグインを次のように追加してください：

導入は読者にコードが_何をするか_を準備させるため、_どのように_かを理解するだけで済みます。また、少し異なることをしている読者のための穴埋めパターンも作成します。

<Steps> 手順内では、直接的な命令形の指示が導入です（「tsconfig.json を追加してください：」の後にファイルが続くのは、番号付きステップでは問題ありません）。

その他のルール：

実際の動作するコードを使用してください。 foo/bar はなし。すべての可能な値ではなく、1 つの現実的な設定を示してください — 読者は 1 つしか持ちません。
ファイルを表すブロックには title= ファイル名を追加してください。読者がコードの配置場所を知るためです。
```
```ts title="src/plugin.ts"
```
前後の変更には、生の ```diff フェンスではなく Expressive Code アノテーションを使用してください。変更された行を del={n} / ins={n} でマークするか、変更されたテキストを del="…" / ins="…" でマークしてください。diff は変更される行に最小限でローカルに保ってください。

次の例は単一行の変更を示しています：
```
```ts del={1} ins={2}
import { definePlugin } from "emdash";
import type { SandboxedPlugin } from "emdash/plugin";
```
```
送信前にレンダリングされたコードをローカルでプレビューしてください。タイプミスは表示を壊す可能性があります。

アップグレードとマイグレーションガイド

既存のプロジェクトを新しいバージョンに移行するのを助けるガイドは、固定された構造に従います。「何をすべきか？」セクションは読者が最も価値を置く部分です — 手を抜かないでください。

以下で始めてください：アップグレード方法、「そのまま動く」かもしれないが動かない場合は読み続けるようにという注記、チェンジログへのリンク。

次に、各破壊的変更を独自のエントリとして列挙してください：

### [名前変更/変更/削除/非推奨]: <機能>

以前のバージョンでは、<1 文、過去形、何をしたか>。

<1 文、現在形、今どう動くか>。

#### 何をすべきか？

<命令形のアクション：更新… / 置換… / 削除…、最小限の diff 付き。>

読者がどう影響を感じるかで動詞を選んでください。新しいデフォルトが値を置き換える場合、それは「変更：デフォルト値」であり、「追加：オプション」ではありません。

破壊的変更とは、読者のプロジェクトへの変更が必要で、さもなければ動作しなくなるものです。事実だけでなくアクションを示してください。「Node.js の最小バージョンは今 X です」ではなく「次のコマンドで Node.js のバージョンを確認し、X 未満の場合はアップグレードしてください」。

EmDash 固有の事項

繰り返し発生する状況のための規約、コントリビューターがそれに遭遇する頻度順です。これは規約のリストであり、どの機能が重要かのランキングではありません。

プラグイン：サンドボックスとネイティブ

サンドボックスとネイティブプラグインは、異なるオーサリング形状を持つ異なるフォーマットです。一方への変更がもう一方に影響することはまれです。ページや例がどのフォーマットについてかを明記してください。サンドボックスプラグインページを編集する場合、ネイティブプラグインの例を変更しないでください。逆も同様です。

ローカリゼーション

ドキュメント PR に messages.po の変更を含めないでください。ワークフローが main へのマージ時にカタログを抽出します。含めるとチャーンとマージコンフリクトが発生します。

実験的機能

実験的フラグの背後にある機能、または RFC の下にある不安定なワイヤフォーマットは、予告なく変更される可能性があります。ドキュメントをスリムに保ち、注意の <Aside> でフラグを付け、RFC または議論を真実の情報源として指してください。不安定なサーフェスを詳細に文書化しないでください。

Atmosphere アカウント

Bluesky とより広い AT Protocol ネットワークの背後にあるポータブルなユーザー所有のアイデンティティが出てきた場合、Atmosphere アカウントと呼び、その用語を一貫して使用してください。最初の言及を Atmosphere ログインガイドまたは atmosphereaccount.com にリンクしてください。did:plc:… とハンドルはその具体的な識別子です。リテラル値が必要な場合に使用してください。

ドキュメントはコード

ドキュメントサイトは EmDash に隣接する Astro プロジェクトです。ドキュメントの変更はコードと同じプルリクエストとレビューフローを経ます。すべてのテキスト変更はレビューを待ちます。表現の変更は文の意味を変えたり、サイトの他の場所で対応する編集が必要になる場合があります。小さく、レビューされ、一貫した変更がサイト全体の一貫性を維持します。