コンテンツにスキップ

ADR-0008: 読者の identity を前提とする機能を作らず、バックエンドを持たない

Status

承認

Context

初期構想は「Knowledge / Learning Platform への発展」を掲げていた。
挙げていた機能は、学習進捗・Bookmark・Highlight・Annotation・Codelab progress・Discussion・Reading history である。
これらを根拠に、Hono + Hono RPC + D1 + KV + 認証のバックエンド構成を将来像として置いていた。

これらを 1 つずつ検討した結果、大半が自前実装を正当化しないことが分かった。

機能 必要なもの 既にある代替
Bookmark 読者の identity ブラウザのブックマーク、Pocket 等
Reading history identity または localStorage CSS の :visited
学習進捗 「完了」の定義 — (記事に完了はない)
ハンズオンの進捗 localStorage —
Highlight / Annotation identity + テキストアンカー Hypothes.is
Discussion — giscus (GitHub Discussions)

どの機能も、次の 3 つのいずれかに当てはまる。

  • ブラウザや第三者が既に解決している。
  • 個人サイトが決して獲得できない読者の identity を要求する。
  • localStorage で足りる。

読者には「個人サイト 1 つのためにアカウントを作る」動機がない。
技術者向けサイトであれば、読者は既にブラウザのブックマークと GitHub アカウントを持っている。

バックエンドを要求しうる残りの機能も検討した。

  • Contact form は小さな POST 1 本で済む。
  • 検索分析は Cloudflare Web Analytics で済む。
  • AI / semantic search は、数百件ならビルド時に embedding を生成して静的な索引として配り、クライアント側で検索できる。
  • CMS は著者向けであり、ホストされた API + DB より、git にコミットするローカルツールのほうが素直である。

サイトの正体として、次の 3 案を比べた。

案 利用者 中核価値 バックエンド
A 匿名の訪問者 読んで理解し、そのまま手を動かして確認する 不要
B 訪問者 + 著者自身 A に加え、著者が自分の網羅状況を画面で見る 不要
C アカウントを持つ学習者 進捗・注釈を伴う学習体験 必須

著者の関心事は「Markdown を 1 枚足すだけで公開できること」であり、PRD の成功条件の 1 つである。著者は、閲覧機能としては要求を持たない。

Decision

「A. 匿名の訪問者向けの公開サイト」を採る。

読者の identity を前提とする機能を作らない

Bookmark / Highlight / Annotation / 読者アカウント / 認証を Non-Goal とする。
「まだ作らない」ではなく「作らない」と決める。

状態を持つ機能は localStorage に限る

機能 実現の手段
ハンズオンの進捗 localStorage
Reading history CSS の :visited (色のみ変更する。ブラウザのプライバシー制限に従う)
Discussion giscus (GitHub Discussions)。読者は既に GitHub アカウントを持つ

localStorage は端末をまたげない。
ハンズオンは 1 台で通すのが普通のため、端末をまたげないことを許容する。

網羅状況を見せる専用の画面を作らない

「どの分類に記事はあるがハンズオンが無いか」を示す表は、バックエンドなしで作れる。
それでも作らない。

  • 分類 × 種別の表は、実質的に分類ごとの索引である。分類に索引ページを持たせない決定と衝突する。
  • 一覧の表は分類の列を持つ。網羅状況の表を作ると、同じ情報が 2 箇所に載る。
  • 欠けている主題を知りたいのは著者だけであり、著者はコンテンツを自分で書いている。

バックエンドを持たない

Hono / D1 / KV / 認証を構成に含めない。
Worker はハンドラを持たず、静的アセットの配信だけを行う。
ADR-0005: Cloudflare Workers Static Assets を採用し、基盤を Terraform、deploy を Wrangler が管理する

バックエンドを足す条件を先に定める。
条件を満たさないうちは足さない。

条件 想定される形
Contact form の送信受け口が要るとき /api/contact の POST 1 本
ビルド時に解決できない検索が要ると判明したとき まず静的 embedding 索引 + クライアント検索を試し、それで足りないときのみ

/api/* の URL 予約は維持する。
予約のコストはゼロで、条件が成立したときに URL 設計をやり直さずに済む。

Considered Options

選択肢 強み 弱み
採用: A (Output Portal のみ) 最も小さい。設計不変量も減る 「次に何を書くか」の手がかりを画面から得られない。一覧を分類で並べ替えれば読み取れるが、専用の表ほど直接ではない
C (Learning Platform) を目指す 「Knowledge / Learning Platform」という当初の構想に忠実。進捗・注釈を持つ学習体験は、コンテンツの価値を高めうる 個別機能の大半は、Context の機能の表のとおり自前で作る理由がない。 Bookmark と Highlight は読者が使わない。認証・D1・Hono の運用コストを、使われない機能のために払うことになる。有料教材にするなど別の根拠があれば成立するが、現時点でその意図がない
Bookmark を localStorage で作る identity が要らず、バックエンドも要らない ブラウザのブックマークと機能が重複し、しかも劣る (端末をまたげない、UI が独自)。読者が「サイト独自のブックマーク」を使う理由がない
バックエンドを先に用意しておく 後から機能を足すとき、基盤が既にある 足すべき機能が現時点で 1 つも特定できていない。使われない D1 と認証を運用することになる。判断優先度で将来拡張性を最下位に置く方針と反する

Consequences

Positive

  • 決定していないものを決定したように見せる記述が構成から消える。 認証を前提とする将来構想を持たない。
  • 認証・DB・API を持たないため、運用対象がビルドと deploy だけになる。
    • 1 名運用に見合う。
  • ハンズオンの進捗と Discussion を、バックエンドなしで実現する具体的な手段が定まる。

Negative

  • ハンズオンの進捗が端末をまたげない。
    • 別の端末で再開すると最初からになる。
  • Discussion を giscus に委ねるため、コメントするには GitHub アカウントが要る。
    • 技術者向けサイトのため許容する。
  • 将来「やはり読者アカウントが要る」と判断した場合、この ADR を supersede して認証基盤を新規に作ることになる。