専門用語の多い記事で、ツールチップや脚注を後から足そうとすると、いつも同じところで手が止まります。この用語、読み方はどこに書くの。別名って何のためにあるの。短い説明と詳細説明、両方埋める必要ある。
用語注釈マネージャーの用語辞書（cam_term）は、フィールドが多い分だけ最初は迷います。ただ、必須は用語名だけ。各フィールドの役割さえ分かれば、最小限なら数項目で1件が成立します。ここでは、辞書エントリを1件組み立てる流れを、入れる順番どおりに追っていきます。
まず用語名。ここが検出の軸になる
必須なのは用語名だけです。そして本文から用語を拾う照合は、この用語名と後述の別名を突き合わせて行われます。AIが文脈を読んでいるわけではなく、書かれた文字列をそのまま探す純粋なロジック照合。だから用語名は、本文に実際に出てくる表記で登録するのが基本になります。
たとえば「NISA」を本文でそう書いているなら、用語名は「NISA」。ここを正式名称の「少額投資非課税制度」だけにしてしまうと、本文の「NISA」は拾われません。
読み方は検索と並べ替え用。検出はしない
ここが一番の分かれ道です。読み方（ふりがな）は、用語集ページを50音順に並べたり、管理画面で用語を検索したりするためのフィールド。本文中の用語検出には一切使われません。
だから「にーさ」と読み方に入れても、本文の「ニーサ」というカタカナ表記が自動で拾われることはない。カタカナの表記ゆれを本文から検出させたいなら、読み方ではなく、次の別名に入れます。ここを取り違えると「登録したのに拾われない」が起きます。
別名は表記ゆれを束ねる場所
別名は、同じ用語の別表記をまとめて、そのどれが本文に出てきても同じ説明に結びつけるためのフィールドです。用語名と並んで、検出に使われるのはこの別名。
| フィールド | 例（用語名=NISA） | 検出に使う |
|---|---|---|
| 用語名 | NISA | 使う |
| 別名 | ニーサ、少額投資非課税制度 | 使う |
| 読み方 | にーさ | 使わない（並べ替え・検索用） |
正式名称も、本文で使う略語も、カタカナ表記も、拾わせたいものはすべて別名に集約する。この一手間で、同じ用語のゆれをひとつの説明に寄せられます。
短い説明と詳細説明は、出す場所で書き分ける
説明フィールドは2つあります。使い分けの目安はこうです。
- 短い説明：ツールチップに出る一文。ホバーやタップでふわっと出る補足なので、一文で言い切れる長さに収める。
- 詳細説明：注釈ボックスや脚注に出る本文。こちらは限定的なHTMLも使えるので、定義に補足や背景を足したいときはこちら。
同じ用語でも、表示形式（ツールチップ／注釈／脚注）をどれにするかで、読者が目にするのは短い説明か詳細説明かが変わります。両方埋めておけば、後から表示形式を切り替えても説明が空にならず安心です。逆に、ツールチップでしか使わないと決めているなら短い説明だけでも足ります。
なお、色や文字サイズ、脚注の見出しといった見た目は、辞書の各エントリではなく「コンテンツ注釈＞設定＞表示テンプレート」でサイト全体に対してまとめて調整します。辞書側で持つのは「どの表示形式で出すか」まで。1件ずつ色を指定する作業は発生しません。
残りのフィールドは、必要になったときで足りる
詳細URL、カテゴリー、既定表示形式、有効／無効、用語集に掲載するか。この辺りは埋めなくても用語は機能します。
- 詳細URL：ツールチップの「詳しく見る」リンクの飛び先。外部の一次情報（たとえば金融庁のNISA解説ページ）に繋ぎたいときに。
- カテゴリー：階層で持てるので、分野が増えてきたら整理用に。用語集ページでの絞り込みにも効いてきます。
- 既定表示形式：この用語は基本ツールチップ、この用語は脚注、と決め打ちしておける。
- 用語集に掲載：オフにすれば、本文には注釈を付けつつ用語集ページには載せない、という切り分けができます。
一件目から全フィールドを埋めきろうとしなくて大丈夫。用語名と、拾わせたい別名、それに出す場所ぶんの説明。まずはこの3点で1件が動き出します。カテゴリーやURLは、記事本数が増えて「そろそろ整理したい」と思ったタイミングで戻ってくれば十分間に合います。
辞書は一度作れば全記事で共有される資産です。最初のうちは面倒に感じても、1件ずつ丁寧に組んでおくと、後続の記事ほど登録が軽くなっていきます。用語注釈マネージャーの設計も、その「積み上がっていく辞書」を前提にしています。用語辞書を育てる詳しい手順はプラグイン紹介ページも参考にしてください。
