はじめに
技術記事では、読者にとって難しい用語が自然に出てきます。すべてを本文内で長く説明すると記事が読みにくくなりますが、何も補足しないと初心者が離脱しやすくなります。
このブログでは、本文中の重要語にTermコンポーネントを使い、用語集や補足検索へ進めるようにします。
使う場面
- MDX記事を新規作成した後
- 既存記事を初心者向けに読みやすくしたいとき
- Electron、VSTO、WPF、CodeAnalysis、Python Windowsなど専門語が多い記事
- 記事本文に検索して調べたくなる語が複数あるとき
実装パターン
本文では次のように書きます。
<Term>WebAssembly</Term>
<Term>IPC</Term>
<Term query="tkinter">tkinter</Term>
<Term suffix="">VSTO</Term>
通常は<Term>表示語</Term>だけで十分です。表示語と検索語を変えたい場合だけqueryを指定します。
たとえば、GASとだけ表示したいが検索語は「Google Apps Script GAS」にしたい場合は、次のようにします。
<Term query="Google Apps Script GAS">GAS</Term>
選定ルール
1記事あたりのTermリンクは、2から5語程度に絞ります。
リンク化するのは、初心者が調べそうな専門語、この記事の理解に必要な語、別記事や用語集とつながる語です。一方で、一般語、何度も出る語、文脈上すぐわかる語まで毎回リンク化すると、本文が読みにくくなります。
コードブロック内、frontmatter、見出し内には原則として入れません。本文の最初の意味のある出現だけをリンク化すると、読みやすさと補足導線のバランスを取りやすくなります。
作業手順
1. 対象記事を読む
2. 初心者が詰まりそうな専門語を選ぶ
3. 2から5語だけTermで囲む
4. コードブロック内に入っていないか確認する
5. 用語集に未登録らしい語をメモする
6. build対象ならnpm run buildで確認する
用語集の追加まで依頼されていない場合は、terms.tsを触らず、不足語候補として報告します。
注意点
- リンクを増やしすぎると本文の流れが切れます
- 内部導線ではなく、補足理解の軽い導線として扱います
- 顧客名、実パス、非公開サービス名をTerm化しません
- 既存用語にない場合でも、記事作成の範囲外なら勝手に
terms.tsを更新しません
関連記事
まとめ
Termリンク化は、記事本文を長くしすぎずに読者の補足調査を助けるための運用です。
重要なのは、すべての専門語を機械的に囲むことではありません。読者が理解につまずきそうな語だけを選び、本文の読みやすさを保ったまま導線を置くことです。