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

読みやすさ

次のものを優先します。

• 短い文と短い段落。
• 専門用語よりも平易な語彙。
• 略語や頭字語は、初出で省略せずに書く。
• 長い文章は、見出しやリストで区切る。
• 能動態。

EmDashがどう作られているかではなく、EmDashを使ってどう作るかを書きます。実装の詳細をドキュメントに書くのは、それが読者のしなければならない判断を変える場合（初期値以外の値を選ぶ必要がある場合や、読者のプロジェクトに影響する注意点）だけです。実装の詳細が使い方の例の代わりになることはありません。

EmDash以外の話題（TypeScript、AT Protocol、Webフォント、SQL）は、説明する代わりに信頼できる情報源にリンクします。その機能をEmDashで使うために知っておく必要があることを書きます。

強調する内容

ページで何を強調するかは、読者が作業をするのに何が必要かで決めます。EmDashを作った人にとって面白かったことや最近のことで決めてはいけません。意識して避ける習慣が3つあります。

• 書いた時期の新しさによる重み付け。 判断が新しい、または書き手の記憶に新しいということは、それを取り上げる理由になりません。最も変更されたことが、読者にとって最も重要なことである場合はまれです。セクション、リストの項目、見出しは、追加された時期ではなく、読者が必要とする頻度の順に並べます。何かが変わったばかりだからという理由で書いているなら、それはおそらくドキュメントではなく変更履歴の項目です。

• 読者にとっての重要さより、作り手にとっての重要さを優先すること。 作るうえで大きな意味を持った内部のアーキテクチャや設計の判断は、使ううえでは見えず、関係がない場合がほとんどです。その裏にある仕組みではなく、読者が得られる機能を書きます。コレクションを定義する読者が、パーサーの言語を知る必要がないのと同じように、スキーマがどこに保存されるかを知る必要はありません。その仕組みがEmDashの開発に取り組む人に本当に役立つなら、それは利用者向けのページではなく、内部構成のドキュメントに書きます。

• わら人形を使った自己定義。 他のツールを戯画化したものとの対比でEmDashを定義しないでください（「多くのCMSと違って…」「従来のCMSでは…を強いられます」「多くのCMSではXをコードで宣言します」）。EmDashが何をするかを直接説明し、それだけで成り立つようにします。比較してよいのは、その比較が読者自身の疑問である場合だけです。評価のためのページと、「〜から移行する」導入ページがこれにあたります。その場合でも、具体的で公平でなければなりません。読者に嫌わせるためのわら人形ではなく、具体的な動作とトレードオフを示します。

• 否定による定義。 ある機能を、しなくて_よい_作業として表現すること（「書くマイグレーションは不要」「再ビルド不要」「コードに触れずに」「別のサービスは不要」）は、形を変えたわら人形です。書き手が読者のために作り上げた別の方法を、読者が思い浮かべている場合にしか伝わりません。読者が何を_する_か、何が_起きる_かを書きます。「管理画面でフィールドを追加すると、すぐに反映されます」と書き、「マイグレーションも再ビルドもコードも不要でフィールドを追加できます」とは書きません。例外は、読者に関係する具体的な動作を肯定的に書く場合です。「コンテンツは実行時に提供されるため、編集はすぐに反映されます」はEmDashについての事実です。「再ビルドは不要です」は、同じ事実を、他の誰かの苦労がないという形で書いたものです。前者を優先します。

どの文についても、次のことを確かめます。その文を削除したら、作業を終えようとしている読者が困るかどうか。困らないなら削除します。EmDashを他の何かと比べている読者にしか意味が通じない文なら、置き場所が間違っているか、削る対象の文です。

変更履歴ではなく、いつでも通用する内容

利用者向けのページは、以前のバージョンのことを知らない読者に向けて、現在のEmDashの動作を説明します。「現在は」「もう〜しない」「以前は〜していた」「古い〜の代わりに」「これは変更された」とは書きません。バージョン間の違いは、アップグレードガイドにだけ書きます。ある概念が最近導入されたことは、それが最近であると書く理由にはなりません。

文体とトーン

中立的で、事実に基づいた文を書きます。事実をそのまま述べます。

✅ プラグインは分離された実行環境で動き、宣言したAPIにしかアクセスできません。

❌ プラグインは、悪いことが何も起こらない、居心地のよい小さなサンドボックスの中で暮らしています！

• we、us、our、let's を使いません。 書き手は読者と一緒に座っているわけではありません。読者に直接語りかける形か、システムを説明する形に言い換えます。
• I は決して使いません。 ドキュメントは書き手についてのものではありません。
• 必要な場合は、読者を you と呼びます。 特に、何かがうまくいかない可能性のある手順に注意を促す場合です。
• ナレーションや物語のような書き方をしません。 「Xの準備ができたので、次はYに進みましょう」とは書きません。セクションは目的から始め、そのあとに手順を書きます。
• 気の利いた言い回し、マスコット、文化的な引用を避けます。 読む手間が増え、翻訳でも伝わりません。
• 感嘆符はまれにしか使いません。 本当に励ましになることや驚くことにだけ使います。迷ったらピリオドを使います。

見出し

• ページのタイトルは <h1> です（frontmatterの title から作られます）。セクションは <h2> から始めます。
• 見出しは短くします。<h2> と <h3> は「On this page」のサイドバーに表示されます。プレビューで確認し、折り返すものは短くします。
• 末尾に句読点（コロンを含む）を付けません。
• 見出しの中のコードは、本文と同じように <code> で書きます。

リスト

• オプションやプロパティの集まりのように、順番に意味がない場合は箇条書きのリストを使います。
• 順番に従う必要がある手順には、番号付きのリストを使います。手順にはStarlightの <Steps> コンポーネントを使います。
• リストの項目が複数の段落になったり、コードの用語をいくつも含んだりする場合は、代わりに <h3> のセクションに切り替えます。

例

• 1つの例や仮定の話は、省略しない「for example」で導入します。
• 括弧の中の「e.g.」は、すべてではない例の一覧を導入します（e.g. GitHub, GitLab）。
• すべての選択肢を網羅する一覧は例の一覧ではないため、「e.g.」を付けずに括弧を使います（the required properties (src, alt)）。

スクリーンショット

スクリーンショットは、空間的な位置関係、画面の状態、操作する部品の場所を分かりやすくするうえで実質的に役立つ場合にだけ使います。画像がなくてもページが使えるように、手順などの重要な情報は本文に書きます。

スクリーンショットはすべて最新で、そのページの目的に合わせて撮影したものでなければなりません。関係する画面と状態を説明する代替テキストを付けます。他の貢献者が同じ画像を撮影できるように、使ったフィクスチャ、ルート、ビューポート、ロケール、テーマを記録します。

コード例

コード例は、その周りの文章と同じくらい重要です。

すべてのコードブロックの前に、それ単体で完結した文を1行で書き、そのブロックが何をするかを読者に伝えます。コロンで終わる文の断片、見出しだけ、「like so:」のような書き出しで始めないでください。

✅ The following example registers a plugin in the sandboxed array:

❌ Add the plugin like so:

導入の文があると、読者はコードが何をするかを先に知ったうえで、どのようにするかだけを読み解けばよくなります。また、少し違うことをしようとしている読者にとって、空欄を埋めるだけの型になります。

<Steps> の手順の中では、直接の命令形の指示が導入の文になります（番号付きの手順で「Add a tsconfig.json:」のあとにファイルを示すのは問題ありません）。

その他の決まりは次のとおりです。

• 実際に動くコードを使います。 foo／bar は使いません。あり得るすべての値ではなく、現実的な設定を1つ示します。読者が使う設定は1つだけです。

• ファイルを表すブロックには、title= でファイル名を付けます。こうすると、読者はコードをどこに書けばよいかが分かります。

  ```ts title="src/plugin.ts"
  

• 変更の前後を示すには、生の ```diff のフェンスではなく、Expressive Codeの注釈を使います。変更した行は del={n}／ins={n} で、変更したテキストは del="…"／ins="…" で示します。差分は最小限にし、変更する行の周りだけにします。

  次の例は、1行の変更を示しています。

  ```ts del={1} ins={2}
  import { definePlugin } from "emdash";
  import type { SandboxedPlugin } from "emdash/plugin";
  ```
  

• 送る前に、描画されたコードをローカルでプレビューします。タイプミスが1つあるだけで、表示が崩れる場合があります。

アップグレードと移行のガイド

既存のプロジェクトを新しいバージョンに移すためのガイドは、決まった構成に従います。読者が最も重視するのは「What should I do?」のセクションです。手を抜かないでください。

最初に、アップグレードの方法、そのまま動く場合もあるが動かない場合は続きを読むようにという注記、変更履歴へのリンクを書きます。

そのあと、破壊的変更を1つずつ、それぞれ独立した項目として並べます。

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

In earlier versions, <one sentence, past tense, what it did>.

<One sentence, present tense, how it works now>.

#### What should I do?

<Imperative actions: Update… / Replace… / Remove…, with a minimal diff.>

動詞は、読者が影響をどう感じるかで選びます。新しい初期値が読者の値を置き換える場合は、「Added: option」ではなく「Changed: default value」です。

破壊的変更とは、読者のプロジェクトを変更しなければ動かなくなる変更のことです。事実だけでなく、必要な対応を書きます。「Node.jsの最小バージョンはXになりました」ではなく、「次のコマンドでNode.jsのバージョンを確認し、Xより低い場合はアップグレードします」と書きます。

EmDash特有の決まり

繰り返し出てくる状況についての決まりを、貢献者が出会う頻度の高い順に並べています。これは決まりの一覧で、どの機能が重要かの順位ではありません。

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

サンドボックス型プラグインとネイティブ型プラグインは、書き方の形が異なる別々の形式です。一方への変更が、もう一方に影響することはほとんどありません。ページや例がどちらの形式についてのものかを明記します。サンドボックス型プラグインのページを編集するときは、ネイティブ型プラグインの例を変更しません。逆も同じです。

ローカライズ

ドキュメントのPRに messages.po の変更を含めないでください。main にマージされたときに、ワークフローがカタログを抽出します。含めると、無駄な変更とマージの競合が生じます。

実験的な機能

実験的なフラグの背後にある機能や、RFCの段階にある不安定な通信形式は、予告なく変わる場合があります。そのドキュメントは簡潔にし、cautionの <Aside> で注意を示し、正式な情報源としてRFCやDiscussionを示します。不安定な部分を、細部まで網羅して書かないでください。

Atmosphereアカウント

Blueskyや、より広いAT Protocolのネットワークの背後にある、ユーザーが所有して持ち運べるアイデンティティについて書くときは、Atmosphereアカウント（Atmosphere account）と呼び、この用語を一貫して使います。初出は、Atmosphereでのログインのガイドまたは atmosphereaccount.com にリンクします。did:plc:… とハンドルが、その具体的な識別子です。実際の値が必要な場合は、それらを使います。

ドキュメントもコード

ドキュメントのサイトは、EmDashに近いAstroのプロジェクトです。ドキュメントの変更は、コードと同じプルリクエストとレビューの流れを通ります。テキストの変更はすべてレビューを待ちます。言い回しの変更が文の意味を変えたり、サイトの他の場所で同じように直す必要が出たりする場合があるためです。小さく、レビューされた、一貫した変更を積み重ねることで、サイト全体の一貫性が保たれます。