READMEエンジニアリング＆技術ドキュメンテーションガイド

READMEエンジニアリング＆技術ドキュメンテーションガイド は何をしますか？

読者の時間を尊重し、技術的な価値を明確に伝え、一般的なマーケティングの誇張表現を排除した、世界最高水準かつ人間にとって自然なGitHubリポジトリのREADMEを作成するための厳格なフレームワーク。

---

1. 核となる哲学：30秒ルール

開発者やユーザーはドキュメントを最初から最後まで「読む」のではなく、高速でスキャンします。午前2時に偶然あなたのリポジトリにたどり着いた疲れた開発者の立場になって考えてみてください。

READMEは30秒以内に次の3つの質問に答えなければなりません：

1. これは何ですか？ （マーケティングの誇張表現を一切含まない、明確な一文での定義）。
2. なぜ気にする必要があるのですか？ （それが解決する現実世界の問題と、それによって不要になるイライラする回避策）。
3. 今すぐどうやって実行しますか？ （コピペ可能な3ステップのクイックスタートとテスト済みコマンド）。

---

2. 明確で根拠のある文章のためのガイドライン

ドキュメントはしばしば、誇張された企業広報の決まり文句に陥りがちです。高品質なオープンソースプロジェクトは、このようなトーンを完全に避けます。

2.1 禁止用語・決まり文句辞書

❌ 禁止バズワード・決まり文句	✔️ 明確で根拠のある代替案
「今日のめまぐるしいデジタル環境において...」	(完全に削除。問題に直接入る)。
「シームレスに統合/苦労せずに転送...」	「ブラウザからファイルをドロップすると、スマホに表示されます。」
「革新的で最先端のプラットフォーム...」	「軽量なセルフホスト型パーソナルリレー。」
「生産性を新たな高みへ...」	「リンクを自分宛てにメールする手間が省けます。」
「現代開発の証...」	(削除。PR会社ではなくエンジニアのように話す)。
「巨大なヒーローバナーを完全排除」	(内部リファクタリングを自慢しない。今UIが何を提供するかを述べる)。
「防御的Webサインインアーキテクチャ」	「HttpOnly SameSite CookieとCSRFトークンを使用した安全なログイン。」
「ゼロスケルトンSWRキャッシュ」	「瞬時読み込み：白い空白画面なしで受信トレイを開きます。」

2.2 本物らしい文章のためのルール

• 「火曜日のコーヒー」テスト： 下書きを声に出して読んでみてください。思慮深いソフトウェアエンジニアが、同僚にコーヒーを飲みながらお気に入りのツールを説明しているように聞こえますか？ 企業のマーケティングパンフレットのように聞こえるなら、書き直してください。
• バッジの規律： バッジは3～6個の意味のある指標（リリースバージョン、ビルド/CIステータス、ライセンス、コアスタック）に限定してください。プロジェクトから注意をそらす15個の装飾的なシールドを積み上げないでください。
• 前提条件を謎にしない： docker compose up や npm start と書く前に、前提条件と環境認証情報の入手先を必ず列挙してください。

---

3. 二重の読者層のための構造

優れたドキュメントは、明確さを損なうことなく、2つの異なる読者層を橋渡しします：

flowchart TD
    Audience["リポジトリ訪問者"]
    Audience --> HomeUser["1. 一般ユーザー／日常ユーザー<br>(これが自分の問題を解決してくれるか知りたい)"]
    Audience --> Sysadmin["2. エンジニア／システム管理者／開発者<br>(アーキテクチャ、セキュリティ、スタックを知りたい)"]

    HomeUser --> PlainSection["'なぜこれが存在するのか？' セクション<br>- 現実世界の状況（テキストボットやメール添付ファイルはもう不要）<br>- 3ステップの概念的なワークフロー<br>- プライバシーとセルフホスティングの利点"]
    Sysadmin --> TechSection["'仕組み' セクション<br>- アーキテクチャ図（Mermaid）<br>- コンポーネントの責務<br>- セキュリティとトークンモデル<br>- ストレージとデータベースの仕組み"]

3.1 日常ユーザーのための平易な英語

共感できる現実世界の摩擦から始めます：

「自分宛てにリンクをメールしたり、テキストをスマホにコピーするためにTelegramやWhatsAppのボットにメッセージを送ったり、たった1つのPDFを移動するためにクラウドドライブの同期を待ったりしたことはありませんか？ Vaultは、これらの回避策をあなただけのプライベートなドロップボックスに置き換えます。」

3.2 開発者のための根拠のある技術的詳細

正確なアーキテクチャと実装の詳細を続けます：

• APIエンジン： ASP.NET Core 10 Minimal API が最大100MBのファイルをディスクに直接ストリーミングし、SHA-256検証をその場で実行（RAMの肥大化ゼロ）。
• Web SPA： React 19 + TypeScript、SameSite HttpOnly Cookie、CSRFトークン、キーボードショートカット（/ 検索）を採用。
• モバイルクライアント： ネイティブKotlin Jetpack Compose、WorkManagerによるオフラインアウトボックスキュー、Android FileProvider 統合。
• データベース： PostgreSQL 18、メタデータと14日間のスライディングセッショントークンを保存。

---

4. ビジュアルショーケースとUIレイアウト

アプリケーションに視覚的なインターフェース（Web、モバイル、CLI出力）がある場合は、導入後のすぐ後に表示します。

4.1 レスポンシブショーケーステーブルパターン

<table align="center" width="100%">
<tr>
<th width="33%" align="center">📱 モバイル受信トレイ</th>
<th width="33%" align="center">⚙️ デバイスハブ</th>
<th width="34%" align="center">🔐 シームレスなペアリング</th>
</tr>
<tr>
<td align="center" valign="top">
<img src="docs/assets/mobile-inbox.png" alt="モバイル受信トレイ" width="260px" />
<br/>
<sub><i>インスタントローカルキャッシュ、ライブ検索、ワンタップアクション。</i></sub>
</td>
<!-- 残りの列 -->
</tr>
</table>

4.2 スクリーンショットルール：

• 説明的なキャプション： キャプションは、そのビューでユーザーが できること を説明するために使い、バズワードを連ねるためには使わない。
• 実際のスクリーンショット： 偽のラップトップフレームが付いた一般的なモックアップテンプレートではなく、常に実際の製品UIの鮮明なキャプチャを使用する。

---

5. 堅牢なクイックスタートの設計

クイックスタートは、トラブルシューティングなしで再現可能でなければなりません。

標準的な3ステップセットアップ：

### 1. ローカル証明書と認証情報を生成する
```bash
./scripts/setup-local.sh  # または ./scripts/setup-local.ps1

これの目的：信頼されたローカルホストTLS証明書を .local/tls/ に生成し、ランダムなブートストラップパスワードを .env に書き込みます。

2. スタックを起動する

docker compose up -d

3. ワークスペースを開く

ブラウザで https://localhost:8080 にアクセスします：

• ユーザー名： [email protected]（または owner）
• パスワード： .env ファイル内のブートストラップパスワード

---

## 6. 標準README構造チェックリスト

技術リポジトリのREADMEを構成する際は、このチェックリストを使用してください：

- [ ] **1. ヘッダーとタイトル：** ロゴ/アイコン、タイトル、一文の機能的なタグライン。
- [ ] **2. 焦点を絞ったバッジ：** リリースバージョン、ビルドステータス、コアプラットフォーム、ライセンス。
- [ ] **3. なぜこれが存在するのか：** 日常的な問題、その修正、および平易な英語での3ステップワークフロー。
- [ ] **4. ビジュアルツアー：** 実用的なキャプション付きのWeb、モバイル、またはCLIインターフェースのスクリーンショット。
- [ ] **5. コア機能：** 実際のタスクごとに整理されたユーザー中心の機能リスト。
- [ ] **6. 仕組み（技術的）：** Mermaidアーキテクチャ図と簡潔なコンポーネントの内訳（API、クライアント、DB、認証/セキュリティ）。
- [ ] **7. クイックスタート（Docker / ローカル）：** 前提条件、ステップバイステップのコマンド、認証情報の場所。
- [ ] **8. モバイル / クライアントセットアップ（該当する場合）：** 直接ダウンロードリンク、ペアリング手順、LANテストガイド。
- [ ] **9. 自動テストと検証：** バックエンドとフロントエンドのテストスイートをローカルで実行するコマンド。
- [ ] **10. リポジトリマップとコントリビューティング：** きれいなASCIIフォルダツリー、ガイドラインリンク、MIT/Apacheライセンス。

---

## 7. 参考オープンソースリポジトリ

これらの高く評価されているオープンソースのREADMEを、構造と視覚的な参考のために調査してください：

- **`matiassingers/awesome-readme`**： GitHub全体のトップREADMEのキュレーションされたディレクトリ。
- **`othneildrew/Best-README-Template`**： モジュール式で効果の高いリポジトリテンプレートの業界標準。
- **`charmbracelet/bubbletea` & `charmbracelet/gum`**： 卓越したターミナルショーケース、GIFの使用法、スキャン可能なコードブロック。
- **`supabase/supabase`**： 明確なシステムアーキテクチャ図と迅速なオンボーディングを備えた、優れた二重読者層バランス。
- **`fastapi/fastapi`**： 摩擦のないクイックスタート、実際のコード例、明確な価値提案の模範。