【コスト削減約30％以上】AsciiDocとGitHubでPDF、HTMLマニュアルのデータを部署をまたいで一元管理

ヤマハ株式会社グループ　概要

・設立：1897年10月

・資本金：285億34百万円

・従業員数：

　連結 20,175人

・事業内容：

　楽器事業、音響機器事業、部品・装置事業

ご利用サービス

・マニュアル作成

・翻訳

・AsciidocとGitHubを利用したドキュメント編集＆管理システム構築

導入したマニュアル作成フロー

通常のドキュメントの制作フローで使うシステムやツール類を、各種オープンソースソフトウェア（ATOM/RedPen）やGitHub、SourceTreeなどIT分野に馴染みのあるツール類に代替しました。

各工程のデモ動画

1. テキストエディタATOMでAsciiDocを編集し、GitHubでデータを管理する手順です。

2. AsciiDocからAsciidoctor-PDFを使ってHTMLとPDFを出力する手順です。

3. AsciiDocをXMLに変換してTradosを使って翻訳する手順です。

※AsciiDoc（アスキードッグ）とは

軽量マークアップ言語のひとつです。テキストエディターで記述しHTML、PDF、EPUB、などのファイル形式に変換できます。

※GitHub（ギットハブ）とは

ソフトウェア開発に使われるバージョン管理ツールです。ソースコード管理だけではなく、仕様書などのドキュメント管理・共有ツールとしても利用されています。マニュアル作成においては、変更履歴記録、複数ユーザーによる同時作業などが可能です。5ユーザー25ドル/月から利用できます。

背景

音響事業本部開発統括部マニュアル制作グループでは、ルーター、スイッチ、無線LANアクセスポイント等のネットワーク製品のマニュアルを制作しています。

1製品あたりコンシューマ向けと技術者向けの2種のマニュアルが各300ページあり、開発エンジニアが執筆し、マニュアル制作グループがとりまとめてリリースしています。コンシューマ向けのマニュアルはFrameMakerで編集、PDF変換、技術者向けマニュアルは、直接HTMLを編集していました。

【背景①】見栄えを妥協せず、HTMLの直書きによる課題を解消したい

今回の改善に取り組んだ背景として、前述のような従来の制作手法において次のような要望やHTMLの直書きによる課題が上がっていたことがあげられます。

・工数を削減したい。
・文法のミスによる品質低下を解消したい。
・インデントの変更やタグの変更など文章と関係ないところでのバージョン管理を解消したい。
・HTMLのみならずPDFなどにも変換したい。

今回の取り組みを行う前のHTMLマニュアルは次のようなページでした。

【目標①】Asciidoc（軽量マークアップ言語）を採用し、HTMLマニュアルを制作する

今回の取り組みを進めるにあたり、一つ目の目標を「Asciidoc（軽量マークアップ言語）を採用し、HTMLマニュアルを制作する。」と定めました。

具体的な施策として次の2点を実施しました。

・技術資料向きのAsciidocを採用し、表組みなどを積極的に取り入れたHTMLマニュアルを完成させる。
・CSSやJavaScriptを活用し、レイアウトの見栄えを強化する。
・これらを実施した結果、以下のようなページを作り上げることができました。

【背景②】従来のDTPツールを使用したマニュアル制作の課題を解消したい

もう一つの背景として、従来のDTPツールを使用してのマニュアル制作における課題を解決したいという思いがありました。課題は以下のような作業を発注する側の社内ならではものでした。

・通常は社外制作のため、複雑なDTPツールを自社内のメンバーが使いこなすにはハードルが高い。
・簡単な追加修正事項の発生都度、社外のDTP作業/検収費用の追加が必要になる。
・DTPツール、有料フォントにライセンス費用が発生するため、自社内の社員のPCに充分な制作環境を用意する必要がある。
・DTPツールのバージョンなどPCの制作環境を一律に揃える必要がある。
・紙マニュアル用が基盤となるDTPデータをHTMLマニュアル用にレイアウトを調整するには追加作業が必要になる。
・紙マニュアル用のPDFとHTMLマニュアルのHTMLの両方を制作するには通常は別々に費用がかかる。

【目標②】効率化と費用削減を図った新たなマニュアル制作システムを構築する

そこで二つ目の目標に「効率化と費用削減を図った新たなマニュアル制作システムを構築」を掲げました。

こちらも具体策として以下2点を実施しました。

・通常のDTPツール/Webサイト制作ツール等を使用せず、簡潔な文法で入力が容易になるように設計された軽量マークアップ言語(Asciidoc)を採用する。
・通常の制作手法(PDF/HTML別々)からワンソースマルチユース(PDF/HTMLマニュアルの自動同時生成)に切り替えてコスト削減を実現する。

これらを実施する目標を「通常の制作コストから約30%以上削減」としました。

導入プロセス

検討、提案期間を経て、2018年1月より、トライアルとして技術者向けAPIリファレンスマニュアルでプロジェクトを開始しました。

【プロセス①】軽量マークアップ言語（Asciidoc）の採用

まず初めに、従来のDTPツールは工程プロセスから外しました。作業環境の準備が難しいことや使いこなすハードルが高いことが理由でした。代わりに、シンプルなテキストエディターを使用して、入力が容易で簡潔な文法をもつ軽量マークアップ言語(Asciidoc)を採用して原稿データを制作することにしました。

【プロセス②】ワンソースマルチユースでのマニュアルデータ制作

軽量マークアップ言語で執筆した原稿データを、データ変換コンバーター（Asciidoctor、Asciidoctor‐PDF）でHTML/PDFデータを同時に自動生成させる仕組みを構築しました。

【プロセス②】レイアウトデザインの強化

課題の一つ目でも述べたように、レイアウトデザイン（見栄え）の妥協はしたくありませんでした。そこで、生成されたHTMLとPDFのレイアウトデザインを強化するために、HTMLにはCSS、PDFには体裁をカスタマイズするスタイルファイル（YAMLフォーマット）を事前にテンプレートとして作成しておき、バッチファイルで自動的に適用させることにしました。

軽量マークアップ言語採用による成果

約30％以上のコスト削減を実現

今回の取り組みによるプロセス改善の効果によって、従来の制作プロセスにおけるステップのいくつかでコスト削減を実現できました。

一番大きかった点は、DTP編集作業がまったく不要になった点です。DTPツールを使った作業にかかっていた時間とコストをゼロにし、テキストエディターと軽量マークアップ言語による作業のみで完結できるようになりました。

全行程を通じて約30%以上のコストを削減できました。

ワンソースマルチユースで先進のドキュメント作成システムを構築したことにより、制作プロセスの効率化と費用削減を実現できました。

今回は取り組みの初回ということで、初期導入費用が必要だった点もあります。

今後このシステムを使っていくことにより初期導入費用の回収も可能だと思っています。

ヒューマンサイエンスへの評価

制作のみならず、ツール・システムの相談ができる会社

もともと、翻訳、マニュアルでお付き合いがありましたが、マニュアルの実制作担当がプログラム、システム知識・スキルに明るく、実制作のみならず、最新技術の情報交換ができるパートナーと認識しています。

AsciiDoc、GitHubの話をしても、スムーズに要件設計が固まり、マニュアル業界ではまだ一般的ではないツール導入が実現しました。

トライアルが終わった段階なので、当初の目的であるエンジニアの工数削減はこれから検証していきます。

今後は、Google Tag Manager やGoogle Analyticsを活用したアクセス解析の導入、アプリ連携を予定しております。拡張への支援を期待しています。

OSSシステム無料ダウンロード

本事例の簡易版OSSシステムをGitHub上に公開しております。

テンプレート、HTML変換、PDF変換の機能を備えたシステムで、テンプレートを活用し、原稿を作成、HTML、PDF生成が可能です。

オープンソースで、GitHubアカウントをお持ちの方であればどなたでも無料でダウンロード可能です。

https://github.com/human-science/adpy/blob/master/README-ja.adoc

adoc、html、pdfフォルダ内よりOSSシステムを使用し生成したサンプル（HTML、PDF）をご確認いただけます。

※PDFは下記ブラウザで閲覧可能です。HTMLはダウンロードの上ご覧ください。

https://github.com/human-science/adpy/blob/master/pdf/ja/toc_ja.pdf

ヤマハ株式会社グループ 概要