[infra] ドキュメント整備の戦略 (README / docs/ / mdbook / rustdoc)

[sotashimozono]

Question

ドキュメント整備の戦略 — 何を、どこに、どの format で書くか。

Proposed document tree

README.md                       # 概要 + 5-min quick start + install
docs/
├── ARCHITECTURE.md             # source tree, module 責任、hot path
├── MCP_TOOLS.md                # 全 MCP tool の reference (引数 / 返り値 / 例)
├── SOURCES.md                  # 各 source の quirks, rate limits, auth
├── STORE.md                    # store layout (BiblioFetch.jl 互換性)
├── SECURITY.md                 # threat model, 何を信頼するか
├── CONFIG.md                   # config.toml, env vars 全部
├── INTEGRATION/
│   ├── claude-desktop.md       # Claude Desktop の MCP 設定例
│   ├── cursor.md
│   ├── codex.md
│   ├── claude-code.md          # ECC user 向け
│   └── obsidian.md             # Obsidian backend 連携
└── CONTRIBUTING.md

Format options

A. Plain Markdown only (推奨)

• GitHub で直接読める、agent も解析しやすい
• 維持コスト最小

B. mdbook で statically generated docs site

• 検索 / sidebar / theming
• GitHub Pages にデプロイ
• 維持コスト中

C. rustdoc only (lib API doc)

• crates.io / docs.rs で自動生成
• でも CLI / MCP はカバーされない

Recommendation

A + C: Plain MD で人向け doc + rustdoc で lib API。mdbook は Phase 6 以降の polish で。

Open questions

• 日本語版 docs を別 dir で持つか (docs/ja/)？英語のみか？
• API reference を docs/ にも置くか rustdoc のみか？
• example code は examples/ dir + docs/ から link？

Decision

???

[sotashimozono]

Filed as external review by Claude (Anthropic, AI agent operating under souta's GitHub auth). Cross-references many other Discussions because each spawns a normative doc.

立場

Recommendation A + C (Plain MD + rustdoc) を 支持。 mdbook は Phase 6+ で十分。 但し、 ここまでの review で増えた normative spec doc が散在するので、 doc tree を再整理し、 各 doc の 権威性 (normative vs informative) と 読者 を明示する提案をします。

1. doc tree の更新版

提案する tree (本文の tree に追加 / 整理):

README.md                       # 概要 + posture statement + install
LICENSE                         # MIT
CONTACT.md                      # takedown / SLA / escalation (#16 §7)
CONTRIBUTING.md                 # contributor 向け、 PR 規約
CODE_OF_CONDUCT.md              # standard

docs/
├── LEGAL.md                    # NORMATIVE — posture, jurisdictional caveats
├── SCOPE.md                    # NORMATIVE — Permanent non-goals (#9, #4)
├── ARCHITECTURE.md             # INFORMATIVE — module 図、 data flow
├── PUBLIC_API.md               # NORMATIVE — semver-locked Rust API (#14)
├── MCP_TOOLS.md                # NORMATIVE — tool spec, schema, error codes (#8)
├── SOURCES.md                  # NORMATIVE — source list, ToS link, prerequisites
├── STORE.md                    # NORMATIVE — schema versioning, flock spec, atomic write (#1, #2)
├── SAFEKEY.md                  # NORMATIVE — algorithm + 100 test vectors (#1)
├── CACHE.md                    # NORMATIVE — resolver / citations cache spec (#8, #6)
├── ERRORS.md                   # NORMATIVE — error code taxonomy × persona (#14)
├── CONFIG.md                   # NORMATIVE — config.toml, env var precedence
├── SECURITY.md                 # NORMATIVE — threat model, supply-chain (#12)
├── MIGRATION.md                # INFORMATIVE — BiblioFetch.jl ↔ doiget (#1)
├── INTEGRATION/
│   ├── claude-desktop.md       # INFORMATIVE — install snippet
│   ├── cursor.md               # INFORMATIVE
│   ├── codex.md                # INFORMATIVE
│   ├── claude-code.md          # INFORMATIVE
│   ├── obsidian.md             # INFORMATIVE — Obsidian sync (#15)
│   └── chain-with-paperqa.md   # INFORMATIVE — composition pattern (#9)
├── PHASES.md                   # INFORMATIVE — Phase plan + status (#7)
└── DECISIONS/                  # ADR (architectural decision records)
    ├── 0001-stdio-only.md      # locks #4
    ├── 0002-no-tdm-default.md  # locks #5
    ├── 0003-out-of-scope-pdf-content.md  # locks #9
    ├── 0004-bibliofetch-coexistence.md   # locks #1, #2
    └── ...

2. NORMATIVE vs INFORMATIVE の権威性区別

各 doc の冒頭に明示的な header を入れる:

> **Status: NORMATIVE.** This document defines binding contracts. Implementations
> MUST conform. Changes require a new ADR in `docs/DECISIONS/`.

または:

> **Status: INFORMATIVE.** This document describes context and rationale.
> It is not binding; consult NORMATIVE docs for contracts.

理由: contributor / AI agent / future reviewer が "この doc を変えていいか" を判断できる。 NORMATIVE 変更は ADR PR 必須にする運用。

3. ADR (Architectural Decision Records) 採用

docs/DECISIONS/ に Michael Nygard 形式の ADR を置く:

# 0001 — MCP transport is stdio only

Date: 2026-05-XX
Status: Accepted
Supersedes: -

## Context
...

## Decision
...

## Consequences
...

各 Discussion で reviewer が提案した Decision を ADR として永続化 することで、 GitHub Discussion が削除されても (本 user 想定の worst case = repo 削除) decision が source 内に保存される。

docs/DECISIONS/INDEX.md で全 ADR を一覧管理。

4. 読者ペルソナ別の entry point

本文 doc tree に対する reviewer 補強:

読者	Entry point
一般 user (CLI)	README.md の "Quick start" + docs/INTEGRATION/
Agent / MCP host integrator	docs/MCP_TOOLS.md + docs/INTEGRATION/claude-desktop.md
Library user	docs/PUBLIC_API.md + crates.io rustdoc
Contributor	CONTRIBUTING.md → docs/ARCHITECTURE.md → docs/DECISIONS/
Publisher legal team	docs/LEGAL.md + CONTACT.md
Security researcher	docs/SECURITY.md + SECURITY.md (vuln disclosure)
BiblioFetch.jl user	docs/MIGRATION.md + docs/STORE.md

README.md の "Documentation" セクションにこの table を置き、 各読者を最短経路で導く。

5. Localization

#14 §4 で reviewer は EN-only を Phase 0-3 で提案済み。 本文 open question への reviewer 回答:

• Phase 0-5: EN only。 docs/ 配下は全部 EN
• Phase 6+: 日本語版を docs/ja/ に作る (ただし NORMATIVE doc は EN を canonical、 日本語版は informative)
• 「日本語が canonical」は将来もしない — 国際 contributor を遠ざける

6. example code の置き場所

本文 open question への reviewer 回答:

• examples/ dir に Cargo workspace member として 各 example crate
• examples/01-basic-fetch/ examples/02-batch/ examples/03-mcp-host-integration/ 等
• docs/ から相対 link で参照 (例: [basic fetch example](../examples/01-basic-fetch/src/main.rs))
• CI で cargo build --examples を試行し、 link rot を防ぐ

7. rustdoc の品質規律

doiget-core (Phase 0 で公開予定の library crate) の rustdoc は厳格に:

• すべての pub item に doc comment 必須 (#![warn(missing_docs)] を crate root)
• 各 trait / struct に doctest example を 1 つ以上
• cargo doc --no-deps -- -D warnings を CI で
• crates.io publish 時に docs.rs で自動 build される

8. CHANGELOG.md と semver の連動

本文 doc tree にない:

• CHANGELOG.md を Keep a Changelog format で
• semver bump (major / minor / patch) と CHANGELOG entry を 1 PR に紐付ける CI rule
• release.yml で git tag に CHANGELOG section を Github Release description として paste

これは agent / CI tool が「version X.Y.Z で何が変わったか」を programmatically 取れるようにする。

9. mdbook を Phase 6 で考える時の準備

reviewer は Phase 6 まで mdbook 不要に同意。 但し Phase 0 から mdbook へ移行可能な structure で md を書いておくと後で楽:

• 各 md ファイルは ATX heading (# ##) のみ
• 内部 link は 相対 path のみ (絶対 URL を使わない)
• 画像は docs/_images/ にまとめる

これを CONTRIBUTING.md の "Doc style" section で明記。

Reviewer Decision proposal

• Decision: A + C (Plain MD + rustdoc)、 mdbook は Phase 6+
• doc tree を本文 + reviewer 追加 (12 件) で再構成
• 各 doc に NORMATIVE / INFORMATIVE status header を明示
• docs/DECISIONS/ で ADR を運用 (Discussion 削除 worst case の保険)
• README.md に persona × entry point table を置く
• Localization: Phase 6+ で docs/ja/、 NORMATIVE は EN canonical
• examples/ を Cargo workspace member、 cargo build --examples を CI
• rustdoc は missing_docs warn + doctest 必須
• CHANGELOG.md を Keep a Changelog format で運用
• mdbook 移行可能な md スタイルを Phase 0 から

最終 Decision 権は author に留保。

---

Reviewer: Claude (Anthropic). Filed 2026-05-05.