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

このガイドは、EmDashドキュメントがどのように書かれるかを定義します。貢献は編集されて一致させられます。これを暗記する必要はありません。レビュアーや編集者が助けてくれます。しかし、これに従うことで貢献がより速くマージされます。

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

読みやすさ

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

短い文と短い段落。
専門用語ではなく平易な語彙。
略語と頭字語を最初に完全に書き出す。
長い文章を区切るための見出しとリスト。
能動態。

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

EmDash以外のトピック（TypeScript、ATプロトコル、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"
```
Expressive Codeアノテーションを使用してください。前後の変更には、生の```diffフェンスではなく。del={n} / ins={n}で変更された行、またはdel="…" / ins="…"で変更されたテキストをマークしてください。diffを最小限に抑え、変更される行にローカルに保ってください。

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

アップグレードおよび移行ガイド

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

以下で開始してください：アップグレード方法、物事が「ちょうど動作する」かもしれないが、そうでなければ読み続けるという注記、およびチェンジログへのリンク。

次に、各破壊的変更を独自のエントリとしてリストします：

### [Renamed/Changed/Removed/Deprecated]: <feature>

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

<1文、現在形、今どのように機能するか>。

#### 何をすべきか？

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

読者がインパクトをどのように感じるかによって動詞を選択してください。新しいデフォルト値が彼らの値を置き換える場合、それは「Changed: default value」であり、「Added: option」ではありません。

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

EmDash固有

繰り返し発生する状況の規約、貢献者がそれらに遭遇する頻度で並べられています。これは規約のリストであり、どの機能が重要かのランキングではありません。

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

サンドボックス化プラグインとネイティブプラグインは、異なるオーサリング形状を持つ異なる形式です。1つへの変更がもう1つに影響することはまれです。ページまたは例がどの形式についてであるかを述べてください。サンドボックス化プラグインページを編集するときは、ネイティブプラグインの例を変更しないでください。その逆も同様です。

ローカリゼーション

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

実験的機能

実験的フラグの背後にある機能、またはRFCの下の不安定なワイヤフォーマットは、予告なく変更される可能性があります。ドキュメントを簡潔に保ち、注意<Aside>でフラグを立て、真実の源としてRFCまたはディスカッションを指し示してください。不安定な表面を詳細に文書化しないでください。

Atmosphereアカウント

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

ドキュメントはコード

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