【コラム】WordからWebマニュアルへ – Jamstackで広がる選択肢

みなさん、こんにちは。ヒューマンサイエンス ドキュメントソリューション部の吉本です。 働き方が多様化している近年、マニュアルの活用シーンも変わってきています。また、DX(デジタルトランスフォーメーション)が進む中、弊社にもマニュアルを「紙ベースからデジタル化したい」「Webマニュアルを公開したい」というご相談が増えてきています。 今回のコラムでは、以下のようなお悩みにお答えします。
「Webマニュアルのメリットは?」
「Webマニュアルのデータ管理はどうすれば良いの?」
マニュアルをWeb公開する方法はたくさんあります。今回もIT企業のエンジニアの方々がマニュアルを作成している場合にメリットのある手法をご紹介したいと思います。エンジニアにとって親和性があり、効率的なWebマニュアル作成・管理方法についてぜひ参考にしていただけたらと思います。
- 目次
1. マニュアルのWeb化によるメリット
そもそもマニュアルをWeb公開することにはどんなメリットがあるのでしょうか。以下に「読み手」「作り手」の視点に分けて7つのメリットをまとめてみました。
「読み手にとってのメリット」
1. アクセスの手軽さ:
従来のようなWord/PDFで共有されているマニュアルは、ファイルの保管場所に悩まれるケースが良くありました。特にリモートワークが普及している昨今、これまで紙で管理していた企業ではマニュアルのデータ化に取り組んだ結果、マニュアルへのアクセスが悪いというご相談をいただくケースもありました。
一方、Webで公開されているマニュアルは、スマートフォンやPCからいつでもアクセス可能です。特定の場所や時間に縛られず、必要な情報を即座に取得できるのは、急なトラブル対応や不明点の解消に非常に役立ちます。ただしアクセス権の設定やセキュリティ面のリスク回避が必要です。
2. 常に最新の情報:
IT企業で作成されるマニュアルの多くは、内容の更新が頻繁にあります。その場合、紙マニュアルでは、再印刷や再配布を行わなければならず、古い情報が混在し続けるリスクがあります。Web上のマニュアルは、新しい情報や修正があった場合にリアルタイムで更新が可能です。 読者は常に正確で最新の情報を手に入れることができるため、誤った操作や誤解を生むリスクが低減します。
3. 検索機能の利用:
印刷されたマニュアルでは、目次や索引を頼りに情報を探す必要があります。しかし、Webマニュアルでは検索バーにキーワードを入力するだけで関連情報を瞬時に表示できます。
4. リンクや動画の埋め込み:
Web上の文書には、関連するページや外部リソースへのハイパーリンクを簡単に埋め込むことができます。これにより、読者は関連情報へとスムーズに移行できます。また、実際の操作方法や製品のデモンストレーションを示す動画を埋め込むことで、文字だけでの説明よりも直感的に理解を深めることができます。
「作り手にとってのメリット」
5. メンテナンス性:
Webマニュアルは、コンテンツ管理システム(CMS)を使って、短時間で内容の変更や追加ができます。これにより、製品のアップデートや新しい機能の追加に迅速に対応することが可能となります。
6. フィードバックの収集:
Webマニュアルにコメントセクションやアンケートフォームを組み込むことで、読者からの意見や質問を直接受け取ることができます。これにより、マニュアルの不足点や改善点を迅速に把握し、よりユーザーのニーズに合った内容に更新することが可能となります。
7. バージョン管理:
Webマニュアルは、Gitなどのバージョン管理ツールと連携させることで、マニュアルの更新履歴を詳細に追跡できます。これにより、いつ、誰が、どの部分を更新したのかを明確に知ることができ、必要に応じて以前のバージョンに戻すことも簡単です。
以上の点から、マニュアルWeb化のメリットを感じていただけたことと思います。 では実際に、マニュアルWeb化の方法をご紹介していきます。これまで弊社は、Web公開するために、HTML変換ツールを開発し、マニュアル制作×Web公開をサポートしてきました。
2. マニュアルをWeb公開するメリットと方法:ソフトウェア開発会社の事例紹介
一例として医療系のソフトウェア開発を提供している株式会社両備システムズ様にて、マニュアルのWeb化に取り組まれた事例をご紹介します。
(詳しくはこちらをご覧ください。Markdownを利用したHTML/PDFマニュアル作成システムの構築)
導入前の課題
①画面や機能を説明した内容になっており、ユーザーの視点に立っていない
②お客様ごとに一部内容が違うマニュアルを管理しており、共通部分のマニュアル更新作業に多大な時間がかかっていた
③作成者によってマニュアルの体裁が異なっていた
④Wordでマニュアルを作成していたが、今後はWebマニュアルが必要
マニュアルが画面・機能の説明に終始し、わかりにくさのため、問い合わせが絶えない状況でした。 そこで、ユーザー指向のマニュアルになるように構成と内容を見直し、形式をPDF/HTMLへ変更する方針に固まりました。
導入のプロセス
①Markdownの採用
両備システムズ社内では、以前からGitHubを導入し、Markdownにて仕様書を作成していました。マニュアルの原稿データをWordからMarkdownに置き換えることで、仕様書の作成時と同様の環境でマニュアルのメンテナンスを行うことができるため、マニュアルでもMarkdownを採用することに決定しました。
②ワンソースマルチユースでのマニュアルデータ制作
Markdownで作成した原稿データをHTMLとPDFの双方に変換する方法として、オープンソースのドキュメント作成ツールGitBookを用いた出力システムを構築しました。
・HTMLマニュアル
・PDFマニュアル

③補助ツールの開発
MarkdownからHTML/PDFへの変換システムを確立後、より簡単にマニュアルのメンテナンスを進められるよう、いくつかの補助機能を備えたGUIツールを開発しました。 例えば、本システムの基本仕様では、マニュアルの章・節の順序を変更するには手動でMarkdownファイルに変更を加える必要がありましたが、GUIツールにより、直感的な操作で順序変更ができるようになりました。
いかがでしょうか。エンジニアにとって親和性があり効率的なWebマニュアルの作成方法について少しだけイメージしていただけたかと思います。
現在弊社では、時代に合わせたよりモダンな手法でWebマニュアルを構築する手法を研究しています。その方法についても紹介させていただきます。
3. Jamstackを利用したマニュアルWeb化の選択肢
Jamstackは、JavaScript、API、Markupの頭文字をとったものとして始まりました。現在ではさらに進化したため、必ずしもこれらの頭文字が表す技術構成にとどまりません。代表的なものとして以下のような手法があります。
1. 静的サイトジェネレーター
静的サイトジェネレーターとは、生データとテンプレートを基に、完全に静的なHTML Webサイトを生成するツールのことです。つまり、サイトでこれまでコンテンツ管理システム(CMS)などを用いて動的に表示していたページを先にHTMLとして生成しておいて、そのHTMLを表示するというWebサイト作成の原点に立ち返るような発想の仕組みです。Jamstackという開発手法の一つとして脚光を浴びることとなりました。
静的サイトジェネレーターにより生成されたHTMLにはデータが埋め込まれた状態になります。ページアクセス時の初期表示のパフォーマンス向上に大きなメリットをもたらします。 代表的な静的サイトジェネレーターには、GatsbyやEleventyなどがあり、これらのツールを活用することで、マニュアルのコンテンツを効率的に管理し、高速なWebページを生成することができます。
(静的サイトジェネレーターについてさらに知りたい場合はこちらをご覧ください。静的サイトジェネレーターとは)
2. ヘッドレスCMS
ヘッドレスCMSを利用することで、マニュアルのコンテンツを簡単に作成管理することができます。弊社ではStoryblokを導入することで、マニュアルのコンテンツを柔軟に更新・編集しています。
・Storyblokの編集画面

3. CDN(Content Delivery Network)
CDNとは、Webコンテンツを高速に、効率的に配信するための分散サービスのことを指します。多くのサーバーが世界中の異なる地域に配置され、ユーザーに最も近いサーバーからコンテンツを提供することで、Webページの読み込み速度を大幅に高速化します。Jamstackの手法において、CDNは静的なコンテンツの配信において中心的な役割を果たします。
CDNを利用することで、静的サイトジェネレーターで生成された静的なHTMLやヘッドレスCMSから取得したコンテンツを、グローバルなユーザーに対して迅速に配信することが可能となります。これにより、ユーザーはどこにいても高速にアクセスでき、マニュアル運用に大きなメリットを与えます。
従来のWebマニュアルを作成する方法からさらに進化している様子を感じていただけたでしょうか。Jamstackを利用したマニュアルのWeb化は確かに「速い」「簡単」「セキュア」な環境で、読み手にとっても、作り手にとっても大きなメリットがあるのです。 でもそれだけではありません。さらに、管理者側にとって大きなメリットがあります。
4. GitHubによるマニュアルドキュメント管理
GitHubはソースコードだけでなく、ドキュメント管理にも役立ちます。先ほどご紹介した株式会社両備システムズ様も活用された方法です。WordPressなどの一般的なCMSはデータベースに記事データがありますが、多くの静的ファイルジェネレーターでは記事データはMarkdown(記法)ファイルなどのテキストファイルとして用意し、Gitのリポジトリに保存するという仕組みになっています。
この方法だとビルドの際、必要なファイルを読むだけでデータが取得できる上、ファイルの履歴もGitで管理されます。何か問題が起きたとしても、Gitで管理されているので簡単に元に戻せるメリットがあります。
例えば、マニュアルの作成や更新には、複数の人が関与することがあります。しかし、複数の人が同時に作業を行うと、変更の競合や誤った変更の統合などの問題が発生する可能性があります。また、変更履歴の追跡や特定のバージョンへの戻り方も困難です。
Gitを使用することで、これらの課題を解決することができます。複数の人が同時に作業を行う場合でも、各自がローカルリポジトリで変更を行い、変更の統合を行うことができます。また、変更履歴はコミットとして保存され、変更の目的や内容が明確になります。特定のバージョンへの戻り方も簡単であり、誤った変更を取り消すことも容易です。
さらに、Gitではブランチを使用することで、特定の部分の修正を行う際に他の作業に影響を与えることなく作業を進めることができます。修正が完了したら、マージを行い、変更を統合します。これにより、マニュアルのバージョン管理と変更履歴の追跡が容易になります。
Gitを使用することで、マニュアルのバージョン管理や変更履歴の追跡、チームでの共同作業やコラボレーションの改善が可能となります。エンジニアがマニュアル作成に携わっている環境においてはとりわけ、Gitはメンテナンス性の向上に大きな助けとなるでしょう。
5. ヒューマンサイエンスならマニュアル作成からモダンフロントエンドを使ったWeb構築まで一貫して対応可能
いかがでしょうか。今回はWebマニュアルを作成する方法をご紹介しました。モダンな手法でマニュアルを制作することは、読み手だけでなく管理者側にも作り手側にも大きなメリットをもたらすことでしょう。
本コラムの内容でさらに詳しくお知りになりたい方はぜひ当社へお問い合わせください。 ヒューマンサイエンスは、1985年以来、数多くのマニュアルを作成してきた実績を持っています。まさに、業務マニュアル作成におけるプロフェッショナル集団です。業務マニュアルの作成でお困りのことがあれば、お気軽にご相談ください。
特長①:大企業・グローバル企業を中心に豊富なマニュアル制作実績
ヒューマンサイエンスは、製造業やIT業界を中心に製造業やIT業界を中心に、多岐にわたる分野でマニュアル制作実績を積み重ねてきました。
これまでに「ドコモ・テクノロジ株式会社」「ヤフー株式会社」「ヤマハ株式会社」など、名だたる企業をクライアントとしてきました。
特長②:経験豊富なコンサルタントによる調査・分析からアウトプットまで
業務マニュアル作成に携わるのは、ヒューマンサイエンスが誇る経験豊富なコンサルタントになります。熟練のコンサルタントが、豊富な経験と提供された資料から、より分かりやすく効果的なマニュアルを提案します。また、情報が整理されていない段階からのマニュアル作成も可能です。担当のコンサルタントがヒアリングを行い、最適なマニュアルを作成いたします。
マニュアル評価・分析・改善提案サービス| ヒューマンサイエンス
特長③:マニュアル化だけでなく、定着支援も重視
ヒューマンサイエンスは、マニュアル作成にとどまらず、”定着化”という重要な段階にも注力しております。マニュアル作成後も、定期的な更新やマニュアル作成セミナーを通じて、マニュアルの定着を支援してまいります。多岐にわたる施策により、現場でのマニュアルの有効活用をサポートいたします。
最後まで読んでくださり、ありがとうございました。 このブログが見やすいマニュアル作りへのヒントになれば、うれしく思います。 次回のコラムでは、「エンジニアの負担を軽減するマニュアル作成の仕組みづくり」について取り上げます。お楽しみに!
IT企業向けドキュメントソリューションのご紹介
IT企業におけるドキュメントソリューションに求められるポイントとは?プラットフォーム選定のポイントや開発者にとって親和性の高いドキュメント作成環境をご紹介します。
【主な内容】
- ドキュメントプラットフォーム選定とは?
- プラットフォーム選定に必要な観点
- 開発者向けドキュメントに求められる3つのポイント
- ドキュメントを資産化する~開発者にとって親和性のあるドキュメント作成環境とは?
- まとめ