Visual Studio Code（VSCode）とは？AsciiDoc文書を作成・編集するメリットから方法、事例まで解説！

1.Visual Studio Code（VSCode）とは？

Visual Studio Code（ビジュアル・スタジオ・コード）は、その名の通りMicrosoft社が開発・提供している無料のソースコードエディタです。一般的に「VSCode」と略され、世界中の多くの開発者に利用されています。
主な用途はプログラミングですが、その高いカスタマイズ性と豊富な機能から、技術文書やマニュアル作成など、幅広いシーンで活用されています。
主な用途:
• プログラミング
• ソースコードのデバッグ
• Gitを利用したバージョン管理
• リモート開発

1-1.VSCodeの主な特徴

VSCodeが多くの開発者から支持される理由は、その優れた特徴にあります。
• 豊富な拡張機能: マーケットプレイスには数多くの拡張機能（プラグイン）が公開されており、必要な機能を追加して自分好みにカスタマイズできます。AsciiDocのサポートもこの拡張機能によって実現します。
• マルチプラットフォーム対応: Windows、macOS、Linuxの主要なOSに対応しており、どの環境でも同じように利用できます。
• Gitとの連携機能: 標準でバージョン管理システムGitの機能を統合しており、GUI操作で直感的にバージョン管理を行えます。
• クラウド連携: ローカルでの開発はもちろん、拡張機能を使えばクラウド環境との連携もスムーズに行え、一つのエディタでシームレスな作業が可能です。

 

2.Visual Studio CodeでAsciiDoc文書を作成・編集するメリット

なぜドキュメント作成にVSCodeとAsciiDocの組み合わせが適しているのでしょうか。

2-1.AsciiDocとは

まず、AsciiDocについて簡単にご紹介します。AsciiDocは、プレーンテキストで記述できる軽量マークアップ言語です。人が読み書きしやすいシンプルな記法ながら、書籍や論文のような複雑な構造のドキュメントまで表現できる高い柔軟性を持ち合わせています。

AsciiDocとMarkdownの違いや、より詳しい活用方法については、こちらの記事もご覧ください。
【関連リンク】AsciiDocとMarkdownとは？活用方法からメリット、違いを徹底比較！

これまで、AsciiDocの作成にはAtom（2022年に開発終了）やAsciidocFXといったエディタが使われてきましたが、現在ではVSCodeが主流の選択肢となっています。

2-2.VSCodeでAsciiDocを扱うメリット

VSCodeでAsciiDoc文書を作成・編集することには、以下のような大きなメリットがあります。

•プレビュー機能付きの強力な拡張機能: 拡張機能「AsciiDoc」をインストールするだけで、エディタ画面の横にリアルタイムでプレビューを表示できます。記述した内容がどのように出力されるかを常に確認しながら執筆できるため、非常に効率的です。
• Gitなど他ツールとの統合が容易: VSCodeはGitとの連携が標準で組み込まれているため、AsciiDocで作成したドキュメントの変更履歴を簡単に管理できます。差分の確認やコミット、ブランチの切り替えといった操作をエディタから離れることなく行えます。
• 軽量で高速な動作: 高機能でありながら、エディタ自体の動作は非常に軽快です。ストレスなく長文のドキュメント編集に集中できます。
• マルチプラットフォーム対応: OSに依存しないため、WindowsユーザーとMacユーザーが混在するチームでも、同じ環境でドキュメント作成・管理が可能です。

3.Visual Studio CodeでAsciiDoc文書を作成・編集する方法

ここからは、実際にVSCodeでAsciiDoc文書を作成するための手順を解説します。

3-1.環境構築

まず、PCがVSCodeのシステム要件を満たしているか確認しましょう。最新のOSであればほとんどの場合問題ありません。詳細は公式サイトをご確認ください。
公式サイト：Visual Studio Code System Requirements

3-2.ダウンロードとインストール

公式サイトから、ご自身のOSに合ったインストーラーをダウンロードし、画面の指示に従ってインストールしてください。
公式サイト：Visual Studio Code

3-3.日本語化

インストール直後はUIが英語表記のため、日本語化すると使いやすくなります。
1. 左側のメニューから拡張機能アイコン（四角が4つ並んだアイコン）をクリックします。
2. 検索ボックスに「Japanese Language Pack」と入力します。
3. 表示された拡張機能をインストールします。
4. 再起動を促されたら、再起動するとUIが日本語化されます。

3-4.拡張機能「AsciiDoc」を追加

次に、AsciiDocを扱うための拡張機能をインストールします。
1. 日本語化した手順と同様に、拡張機能の検索ボックスに「AsciiDoc」と入力します。
2. asciidoctor.asciidoctor-vscode によって提供されている人気の拡張機能が表示されますので、インストールをクリックします。

3-5.AsciiDoc文書の作成

1. VSCodeで新しいファイルを作成し、拡張子を「.adoc」として保存します。（例：document.adoc）
2. ファイルにAsciiDocの記法で内容を記述します。

3-6.出力（プレビューとエクスポート）

拡張機能をインストールしていれば、エディタの右上にあるプレビューアイコン（虫眼鏡の付いた書類アイコン）をクリックすることで、リアルタイムプレビューが表示されます。
プレビュー画面を右クリックすると、「Export as HTML」や「Export as PDF」などのメニューが表示され、簡単に他のフォーマットへ変換・出力できます。

4.活用の流れ：ヤマハ発動機様の事例に学ぶ

VSCodeとAsciiDocを活用したドキュメント管理は、実際にどのような効果をもたらすのでしょうか。ここで、弊社がご支援したヤマハ発動機株式会社様の事例をご紹介します。この事例では、Asciidocとバージョン管理システムGitHubを組み合わせたドキュメント編集・管理システムを構築しました。
※当時はエディタとしてAtomが利用されましたが、現在ではより高機能なVSCodeで同様の環境を構築しています。

• 課題:
◦ コンシューマ向けマニュアルはFrameMaker、技術者向けは直接HTML編集と、制作フローが属人化していた。
◦ ツールが異なることによる作業工数の増大。
◦ 文法のミスによる品質の低下。
◦ バージョン管理の非効率さ。

• 対策:
◦ AsciidocとGitHubを利用したドキュメント編集＆管理システムを構築。
◦ 従来の専用ツールから、Gitや各種オープンソースソフトウェアといったIT分野で標準的なツールに代替。

• 効果:
◦ 制作プロセスが標準化され、約30％以上のコスト削減を実現。
◦ バージョン管理の導入により、品質の一貫性と変更履歴の追跡が容易に。

このように、AsciiDocを軸としたモダンなドキュメント制作フローは、コスト削減と品質向上に大きく貢献します。

【事例詳細はこちら】マニュアル制作の内製化により、約30％のコスト削減を実現

5.まとめ

本記事では、Visual Studio Code（VSCode）を使ってAsciiDoc文書を作成・編集する方法とそのメリットについて解説しました。
• VSCodeは、豊富な拡張機能とGit連携が魅力の無料高機能エディタ
• AsciiDocと組み合わせることで、リアルタイムプレビューを見ながら効率的に執筆可能
• Gitによるバージョン管理で、ドキュメントの品質と一貫性を向上
• ヤマハ発動機様の事例のように、制作フロー全体を改善しコスト削減も実現可能

マニュアルや技術文書の内製化、制作プロセスの効率化は多くの企業にとって重要な課題です。
ヒューマンサイエンスは、日本語版のマニュアル作成から英語および多言語翻訳まで、ワンストップでご支援いたします。1985年からの長きにわたり数々のマニュアルを手がけてきた実績とノウハウを活かし、お客様の課題解決に貢献します。
マニュアルの構築・運用にお悩みの方は、ヒューマンサイエンスの導入支援サービスをご活用ください。GitHubやAsciiDocの活用を通じて、効率的で一貫性のあるドキュメント作成をサポートします。
ぜひお気軽にご相談ください。

GitHub/Markdown/Asciidoc導入支援サービス
【関連記事】Asciidoc変換の方法｜AsciidoctorでできるHTML・PDF出力