利用者向けの説明を作る手順（動画 → 画面マニュアル）

利用者向けの説明は、次の 2 つを、この順で作った。

1. はじめての方へ（docs/guide/）— 朗読つきの動画で、一通りの操作を通して見せる
2. 画面の使い方（docs/manual/）— 画面写真を見ながら、1 か所ずつ調べられる文章

どちらも、アプリを自動で操作して撮る。手で撮らない。 このやり方は、ほかのアプリにもそのまま使えるので、手順と落とし穴をここに残す。

なぜ手で撮らないか

画面は版ごとに変わる。手で撮った動画や写真は、画面を直したとたんに古くなる。 しかも、古くなったことに誰も気づかない。撮り直す手間が大きいので、放っておかれる。

スクリプトで撮れば、画面を直したあとにコマンド 1 つで全部撮り直せる。 画面の言葉を易しくする検討を控えたまま撮影に踏み切れたのも、このため。

なぜ動画を先に作るか

動画を作る過程で、「アプリを外から操作する部品」がそろう。 画面マニュアルは、それを借りるだけで作れる。

• アプリを、操作できる形で起動する仕組み
• ボタンや欄を、座標ではなく名前で探して押す仕組み
• 日本語の名前から、英語の画面の名前を引く仕組み
• 撮影用の素材（見せてよい架空の資料）を作る仕組み

動画のほうが難しい（声の長さと操作の間合いを合わせる必要がある）。 先に難しいほうで部品を作っておくと、写真は部品を借りるだけで撮れる。 逆の順だと、写真用に作った部品が、動画の要求（間合い、カーソルの見せ方）に足りず、作り直しになる。

また、動画を作ると「よく使う道筋」が決まる。 マニュアルは、その道筋の順に節を並べ、 道筋から外れる欄（「前回の受入記録」、「一気通貫」など）を後ろに足す形で書ける。

共通の部品

guide_app.py で差し替えているのは 2 つだけ。

• フォルダを選ぶ窓（ブラウザ版では出ない）— 決めておいたフォルダを、押された順に返す
• 言語の設定の保存先 — 開発者の手元のアプリの設定を書き換えないよう、一時フォルダへ向ける

core/ にも ui/ にも、撮影のための分岐は入れない。写っているのは実物の画面と、実物の処理結果である。

撮り方

uv run --with flet-web==0.86.2 --with playwright==1.63.0 python scripts/docs/capture_manual.py

• 声を使わないので、画面マニュアルの撮影には API キーが要らない（動画のほうは要る。record_guide.py の冒頭を参照）
• 1 回の起動で、SIP 作成 → 中身を見る → AIP 作成 → 中身を見る、を通して操作し、途中で撮る。 写真ごとに起動し直さない。 写真どうしでパスや件数がそろう
• 写真の名前は SHOTS にある。本文はその名前で画像を引く。名前を変えたら本文も直す

踏んだ落とし穴

いずれも、ほかのアプリで同じことをするときに再び起きうる。

隠れた欄を押すと、その上に重なったボタンが押される。 「担当者名」の欄は画面の下に隠れていて、その位置に、画面の下に留めてある「実行」が重なっていた。 欄を押したつもりで実行してしまい、SIP が 2 つできた。写真には何も表れず、出力先を見て初めて気づいた。 対策: 入力の強調を外すときは、右側の空いた所を押す。SIP を作った直後に、出力先に SIP が 1 つだけかを確かめる。

ブラウザ版の Flutter は、日本語の字が欠けることがある。 日本語のフォントを、要る字の分だけ後から取りに行く。届く前に描いた字は空白のまま残る （「素材フ　ルダ」「まだ　りません」）。小さな字で起きやすく、縮小した一覧では見落とす。 対策: 撮る前に窓の大きさを 1 px 変えて戻し、描き直させる。写真は原寸で、小さな字を拡大して確かめる。 実物のアプリは OS のフォントを使うので、これは写真の上だけの問題。

見出しや説明文は、名前で探せない。 Flutter の読み上げ用の層に出てくるのは、ボタン・入力欄・チェックボックスなど操作できるものだけだった。 「何を作るか」のような見出しは出てこない。 対策: 近くのボタンの位置を基準にして、見出しの分だけ枠を上下に広げる（Camera.band）。

ツールチップの付いたボタンは、名前がボタンに付かない。 右上の ⓘ は、名前が外側の層（aria-label）に付いていた。get_by_role("button", name=...) では見つからない。

開いたものは、開いたまま残る。 「オプション」は、SIP 作成で開くと、AIP 作成に切り替えても開いたままだった。 もう一度押すと閉じてしまう。押す前に、中身が見えているかを確かめる。

マウスを載せた場所のツールチップが写る。 撮る前にマウスを画面の端へ動かす。

外部ツールが無いと、見た目は正常なまま中身が違う写真になる。 binaries/（Siegfried・ClamAV）が無いと、全ファイルが「未識別」になり、ウイルス検査は「スキップ」になる。 エラーにはならないので、そのまま撮れてしまう。スクリプトの最初で、無ければ止める。 git worktree では binaries/ が無い（git の管理外なので）。本体の binaries/ へのリンクを置く。

「何も起きていない画面」は、それ自体を撮る。 SIP の段階では「処理の記録」が空で、「記録がありません」と出る。 不具合に見えるので、写真を 1 枚撮り、「これで正常です」と書いた。 同じく、確認が必要な点の囲みを見せるために、撮影用の素材に架空の電話番号を 1 行入れている。

ほかのアプリに当てはめるとき

1. アプリを、画面を見えなくしたブラウザから操作できる形で起動する方法を探す。 Flet／Flutter はブラウザ版で起動できる。Web アプリならそのまま。Electron は Playwright で直接操作できる。 OS のネイティブの画面しかないアプリは、この方法が使えない（別の手段が要る）
2. ボタンを名前で探せるか確かめる。 最初に、画面の部品の名前を一覧にして出してみる （このリポジトリでは、flt-semantics と input の role と aria-label を並べた）。 名前の無い部品が多ければ、アプリの側に名前を付けるほうが先
3. ブラウザ版で動かない部分（ファイル選択の窓など）だけを、起動用のファイルで差し替える。 アプリ本体に撮影用の分岐を入れない
4. よく使う道筋を 1 本決め、動画の台本にする。 台本（1 行 = 操作 1 つ）と朗読の原稿を 1 か所に置き、 動画の声とページの本文を両方そこから作る
5. 同じ部品で、画面マニュアルの写真を撮る。 道筋の順に撮り、外れる欄を後ろに足す
6. 写真を原寸で見て確かめる。 字の欠け、枠のずれ、写り込み、余計な実行の跡（出力先のフォルダ）