Skip to content

WritingDocumentation

Jump to bottom
github-actions[bot] edited this page Sep 9, 2026 · 1 revision

← Home

ドキュメント執筆ガイド

FloatSoda のドキュメントは、読者ごとに User docs / Contributor docs / API Reference の3系統に分かれています(情報設計の正典は Issue #188)。このページは、新しい情報を書くときに「どの系統のどのページに書くか」「何が正典か」「変更したとき何を更新するか」を決めるための入口です。書き方の規約そのものは、それぞれの正典に置いてあり、ここには再掲しません。

系統 読者 答える問い
User docs FloatSoda でアプリを作る人 What / How — 何であり、どう使うか
Contributor docs FloatSoda 本体を変える・レビューする人 How it works / Why / Must — どう動き、なぜそう設計され、何を守るか
API Reference 利用者・コントリビュータ・Coding Agent の全員 Exactly what exists — 公開 API の正確な契約

実装状況 — 系統ごとのディレクトリ(docs/user/、docs/contributor/、docs/api/)への再編は #188 の手順4で進めます。現行の docs/ はほぼ Contributor 向けの密なリファレンスなので、再編では 現行ページを contributor/ へ移し、User docs は新しく書きます。それまでは 再編の地図 で該当ページを選んでください。このガイド自体も、再編後は docs/contributor/Documentation.md へ移ります。Contributor 側の「書くもの / 書かないもの」とテンプレートは、再編で移した実物のページから逆算して Issue #245 で追加します。

1. どこに書くか

書こうとしている情報について、上から順に問いに答えます。

利用者が正しく使うために必要な情報?
 ├─ はい
 │   ├─ 概念を理解するための説明          → User / Concept
 │   ├─ 特定の目的を達成する手順          → User / Guide
 │   └─ 完成物を作りながら学ぶ道筋        → User / Tutorial
 └─ いいえ
     └─ FloatSoda を変更する人に必要な情報?
         ├─ いまどう動いているか            → Contributor / Architecture
         ├─ なぜそう設計したか              → Contributor / Design
         ├─ 変更後も何を維持するか          → Contributor / Requirements
         └─ どう変更・レビュー・公開するか  → Contributor / Development

型・メンバー・引数・戻り値・例外・nullability の正確な公開契約?
 → XML ドキュメントコメント(API Reference の原稿)

境界で迷いやすいものは、次のように分けます。

  • 利用者から観測できる制約は User docs に書き、その制約を成立させている内部要件は Contributor docs に書きます。例: 「WorldSpaceWindow では現在ポインタ入力を使えない」は User docs、「WorldSpaceWindow の入力経路を Controller Ray → HitTest として接続する」は Contributor docs、WorldSpaceWindow のプロパティ・型・例外契約は API Reference
  • Flutter との差異は、判断原則を APIDesign に、確認済み差異の台帳を known-divergences.md に置きます。利用者から見える差異は、該当する User docs のページと、対応するサンプルの「Flutterとの違い」節にも書きます(記録ルールは APIDesign)
  • 同じテーマは1つの系統で詳述し、ほかの系統からはリンクします。概念を Guide で説明し直したり、シグネチャを Concept に並べたりしません

User docs の範囲

User docs は、公開 API と API Reference と合わせて、#188 の層3(統合ミニアプリ型)のサンプルをジュニアコーダーテストで書ける範囲を扱います。これが「どこまで書くか」の合格ラインです。テストで足りないと分かった概念や制約は、User docs か API Reference の不足として回収します(手順は #188)。内部実装を知らないと書けない箇所が見つかったら、それは User docs の穴です。

再編の地図

再編(#188 手順4)の出発点です。現行ページは内部の仕組みの説明が中心なので、User 向けの部分だけを抜き出して新しいページに書き、本体は contributor/ へ移します。種別は再編時に実物で確定します。

現行ページの行き先

現行ページ 行き先 備考
Architecture Contributor / Architecture 利用者向けの全体像は User の「Widget」へ書き下ろす
BuildPipeline Contributor / Architecture
RenderObjects Contributor / Architecture 制約モデルの利用者向け説明は User の「Layout」へ
WidgetSystem Contributor / Architecture 組み込みウィジェット一覧と「押せるボタンを作る」は User 側へ
Animation Contributor / Architecture 使い方は User の「Animation」へ
OVRIntegration Contributor / Architecture オーバーレイ種別と制約は User の「Window / Overlay」へ
UILayering Contributor / Design 設計方針(未提供)
APIDesign Contributor / Design + Requirements
DocumentationComments Contributor / Development
Localization Contributor / Design + Development
このページ Contributor / Development contributor/Documentation.md
TargetUsers User(入口) 利用者向けに書かれているので、ほぼそのまま user/ へ
GettingStarted User / Tutorial 利用者向けに書き直す
Input User / Concept + Guide 利用者向けに書き直す。実装の説明は Contributor 側へ

新しい User ページと元ネタ(#188 の Concept の列挙に沿う)

User ページ 種別 元ネタ(利用者が観測できる制約と使い方を抜き出す)
Widget(宣言的 UI と Widget ツリー) Concept WidgetSystem の組み込み一覧と「押せるボタンを作る」、Architecture の全体像、層1サンプル
State(SetState、InheritedWidget) Concept WidgetSystem、BuildPipeline のうち利用者から観測できる再ビルドの挙動
Layout(制約・サイズ・配置) Concept RenderObjects の制約モデル、層1サンプル(レイアウト基本・制約変換系)
Input(ポインタ・ジェスチャ・アクション入力) Concept + Guide Input、WidgetSystem の「ジェスチャとヒットテスト」、層1サンプル(入力系)。ダッシュボード限定の制約を明記する
Animation Concept Animation
Window / Overlay(ダッシュボード・ワールド座標・デバイス追従) Concept + Guide OVRIntegration、Home の実装状況(表示専用の制約)、Issue #151(物理サイズの発見性)
〜するには(各種) Guide 層2(Cookbook 型)サンプル
GettingStarted Tutorial 現行 GettingStarted、samples/FloatSoda.Samples.GettingStarted
ミニアプリを作る Tutorial 層3(統合ミニアプリ型)サンプル(Phase 2 完了後)

2. 正典の対応表

同じ情報は1箇所にだけ書き、ほかからはリンクします。

情報 正典
API のシグネチャ・引数・戻り値・例外・nullability・副作用・スレッド制約 XML ドキュメントコメント(規約は DocumentationComments)
API の具体的な使い方 User Guide
概念モデル(Widget、State、Layout、Input、Animation、Window / Overlay) User Concept
完成物を作る手順 User Tutorial とサンプル(samples/)
ウィジェットの最小の使用例 サンプルの README(構成は CONTRIBUTING.md の「サンプルを追加する場合の規約」)
内部の動作(ツリー、Build / Layout / Paint、入力、スレッド) Contributor Architecture
設計理由と採用しなかった選択肢 Contributor Design
invariant、observable behavior、ライフサイクル・所有権・スレッドの必須条件 Contributor Requirements
API 設計の原則と Flutter parity / divergence の判断基準 APIDesign
確認済みの Flutter との差異 known-divergences.md
開発・レビュー・リリースの手順 CONTRIBUTING.md / REVIEW.md / RELEASING.md
ドキュメントの分類とサンプルの3層構成 Issue #188

XML ドキュメントコメントは internal / private にも書きます(DocumentationComments の適用範囲)。公開サイトの API Reference に載せるのは public API だけで、internal 側のコメントはコントリビュータ向けの内部資料として扱います。

3. Documentation Impact Matrix

変更の種別ごとに、更新を検討する文書です。その変更によって正典の説明が変わる場合だけ更新します。 全項目を機械的に触る必要はありません。

変更 更新対象
public API を追加・変更する XML ドキュメントコメント。利用者の使い方が増えるなら User Guide と Catalog 型サンプル
observable behavior を変更する User docs とテスト。API 契約に影響するなら XML ドキュメントコメント
公開制約・既知の制限を変更する User docs。必要なら XML ドキュメントコメント
内部アルゴリズムだけを変更する Contributor Architecture の説明が変わる場合のみ
アーキテクチャの境界を変更する Contributor Architecture と Requirements
設計判断を変更する Contributor Design。必要なら Requirements と APIDesign
invariant を追加・変更する Contributor Requirements とテスト
Flutter との差異を導入・変更する known-divergences.md と divergence テスト。利用者から観測できるなら User docs とサンプルの「Flutterとの違い」節
新しい代表ユースケースを追加する User Guide / Tutorial と、#188 の層に沿ったサンプル
サンプルを追加・変更する サンプルの README と checklist.md(CONTRIBUTING.md の規約)
ドキュメントのページを移動・改名する リンク元のページと Home の「ページ一覧」表(公開サイトの検査がリンク切れを検出します)

PR では、テンプレートの ## Documentation 節に、変更種別と更新した正典(更新が不要と判断した場合はその理由)を書きます。レビューでは、その判断がこの表と一致しているかを見ます。

4. User docs のテンプレート

User docs は新しく書くページが多いので、骨格を先に決めておきます。節はページの目的に不要なら省きます。Contributor 側のテンプレートは、再編で移した実物のページから逆算して #245 で足します。

読者は TargetUsers の3タイプです。コードを書くのは LLM で、読むのも LLM という前提を忘れずに、「LLM がこの API を誤用しない」書き方を優先します。Unity しか知らない読者(Booth クリエイター)には、Unity / uGUI の語彙からの読み替えを添えます。

Concept

# 名前
## 概要                        — 何であり、何を解決するか
## いつ使うか
## 基本モデル                  — 利用者から見た仕組み。内部実装は書かない
## 最小例                      — 対応する層1(カタログ型)サンプルへのリンクと、必要なら最小の断片
## Unity / uGUI からの読み替え — 対応する概念と、違う点
## 制約と未実装                — 利用者から観測できる制限。使えるようになる Phase を添える
## 関連ページ

Guide

# 〜する
## 前提
## 手順
## 完成形          — 対応する層2(Cookbook 型)サンプルへのリンク
## 注意点
## 関連 API / サンプル

Tutorial

# 〜を作る
## 作るもの
## 前提
## Step 1 …
## Step 2 …
## 完成            — 対応する層3(統合ミニアプリ型)サンプルへのリンク
## 次に読むもの

サンプルコードは samples/ を正典にし、本文には必要な最小の断片だけを載せます。完全な実装をドキュメント用に別に書きません。

関連

  • DocumentationComments — XML ドキュメントコメントの規約
  • APIDesign — API 設計の原則と Flutter parity
  • TargetUsers — 想定する3タイプの作り手
  • CONTRIBUTING.md — 開発・PR・テスト・サンプルの規約
  • REVIEW.md — レビューの判断基準
  • Issue #188 — ドキュメント・サンプルの情報設計
  • Issue #245 — このガイドの残りの節(Contributor 側の「書くもの / 書かないもの」とテンプレート)
  • Issue #219 — 公開サイト(docs/ の構造がそのままサイトの構造になります)

Pages

Clone this wiki locally