ヴィージェイ物産株式会社が販売しているPDF教材「Claude API + MCP 19台 完全実装ガイド」を v4 にアップデートしました。
このバージョンアップは新しい技術を追加したわけではなく、「読みやすさ」だけのために構造を全面的に書き直したものです。読者の方から「コードがどこから始まるか分からない」「解説がどのコードを指しているか分からない」というご指摘を真摯に受け止め、購入後にスムーズに実装に取りかかれる教材を目指しました。
本記事では、v3 から v4 への 3つの設計変更ポイントをそのまま公開します。教材を販売されている方、技術記事を書いている方の参考になれば幸いです。
変更①：すべてのコードブロックに通し番号を振った
v3 では章ごとにコードが順序なく並んでいたため、「第4章のあのコード、もう一度見たい」となったときに探すのに手間がかかっていました。
v4 では 122 個すべてのコードブロックに通し番号を付けました。第2章のコードは 2-1, 2-2, 2-3 ... 第4章のコードは 4-1, 4-2, 4-3 ... 付録Bのコードは B-1, B-2, B-3 ... というルールです。
本文中で「コード例 4-7 を見てください」と相互参照できるようになり、章をまたいで読み返すストレスが消えました。技術書を書くときに「コード番号は当たり前」と思われがちですが、自己出版PDFだと意外と抜けがちです。v3 を読み返してみて、自分でも探すのに困ったのが導入のきっかけでした。
変更②：解説を「コードの後ろ」に統一した
v3 ではコードの前に長い解説があり、「読みながらコードに辿り着く」流れでした。
しかし実際の学習者は「先にコードを見る → 分からない部分を解説で確認する」という流れの方が自然です。これは技術書を読むときの自分の挙動を観察して気付きました。
v4 では構造を「短い導入1行 → 番号付きコードブロック → コード例 X-Y の解説（■ なぜこのコードが必要か／■ このコードは何をしているか）」に統一しました。
「導入 → コード → 解説」の流れに変えたことで、サンプルコードをすぐコピペして試したい読者と、丁寧に解説を追いたい読者の両方に対応できる構造になりました。
変更③：見出しの色分けでコード境界を視覚化
v3 ではコードと本文の境界が罫線のみで、長いコードブロックの中で「ここからコード」「ここから解説」がパッと分からない問題がありました。
v4 では青タイトルバーをコード本体の見出し（【コード例 X-Y】）に、緑タイトルバーを解説セクションの見出し（【コード例 X-Y の解説】）に、緑文字 ■ 記号を解説内の小見出し（なぜ必要か／何をしているか）に使い分けました。
色だけでなく、コードブロック自体にも太めの青枠を入れて、本文との区別を強化しています。PDFを印刷する方もいらっしゃるので、白黒印刷時にも判別できるよう「太枠＋見出し記号」を併用しています。
数字で見る v3 → v4 の差分
文字数は約13.9万字から約16万字へ、ページ数は75ページから172ページへ、コードブロック数は117個から122個へ。コード番号は「なし」から「すべてに付与」、解説位置は「コード前」から「コード後」、見出し色分けは「なし」から「青／緑で区分」へと変えました。
文字数とページ数が増えていますが、これは「同じ情報をより読みやすく配置し直した結果」であり、コード自体の中身は v3 と同等です。
v4 で変えなかったこと
3つの変更とセットで「変えなかったこと」も明示しておきます。
章構成（第2章〜第22章 + 付録A・B）は v3 のまま。専門用語の括弧書き補足（MCP・LWA・OAuth・SP-API など）は継承。自然な日本語表現（「歴史的経緯」のような不自然な定型句は引き続き排除）。各章末の「ここまでで身につくこと」「次に進む準備」セクションは維持。
「変える部分」と「守る部分」を明確にすることで、v3 を読まれた方が違和感なく v4 に移行できる作りを意識しました。
まとめ
技術書を書く方や、有料コンテンツを販売されている方にお伝えしたい3点です。
第一に、読者は「先に正解（コード）を見たい」ため、解説は後置の方が学習効率が高い。第二に、番号は通し番号にすることで、章を超えた相互参照が可能になる。第三に、コードと解説の境界を視覚的に明示することで、色とアイコンで瞬時に判別できる。
地味な改善ですが、購入後の「使い始めまでの時間」が体感で半分以下になる効果があります。次回はこの v4 を実際に運用しながら、追加で改善した点を v5 としてリリース予定です。
ヴィージェイ物産株式会社では、Claude API・MCP サーバー運用・EC モール自動化に関するご相談を承っております。ココナラの出品サービスからお気軽にお問い合わせください。
