PJ活動お役立ちコラム
第23回　2021年05月04日
効率化とデータ活用を見据えた技術文書作成のあり方

プロジェクトに関わる技術文書やマニュアル作成の効率化を目指し、「マークアップ言語」を採用されているケースもあるかと思います。
このマークアップ言語は技術文書作成の効率化のみならず、使い方によっては文書化した情報のデータ活用にも生かせるメリットもあります。
今回はこの「マークアップ言語」の現状や、導入に向けての進め方など整理してみたいと思います。

マークアップ言語とは、簡単に言うと、タグ付けにより文書を構造化するための言語です。
このタグ付けにより、文書の見栄えを良くしたり、情報を活用しやすくしています。
マークアップ言語は、古くはSGMLから始まり、Web表示用のHTML、情報を取り出し活用しやすくしたXML、さらにはHTMLをXMLで定義したXHTMLなどがあることはご存じかと思います。ちなみにそれぞれの「ML」の部分は「Markup Language」の略となります。

技術文書作成のためのマークアップ言語

そして、前述したSGMLやXMLから派生する形で、技術文書作成に特化したマークアップ言語が存在します。DocBookやDITAなどは標準化団体であるOASISの標準仕様となっている技術文書作成のためのマークアップ言語です。
これらは前出のマークアップ言語同様に、タグをつけたテキストデータを用意したあと、専用の組版ソフトに通すことで、PDFやEPUB、HTML形式の文書ファイルとして出力可能です。
タグによって文書の体裁は自動的に整えられるので、文書作成ソフトでの作成のように手作業でのレイアウト調整は不要です。
またタグ付けした箇所は、リンク設定や検索など様々な機能を効率よく実現するためにも活用できます。
特にDITAは、文書データを章・節・項などの細かい単位で分割管理できるため、異なる文書間でのデータ再利用も可能で、多くの企業で採用実績があります。

実際に文書を作成するには、以下の環境を用意することで実現できます。

技術文書作成に特化したDocBookやDITAですが、作成に必要なタグや文書構造を覚える必要があり、作成する文書や目的によっては機能的に過剰なこともあります。
このため、よりシンプルな記述で比較的簡単な文書を作成できる「軽量マークアップ言語」も存在します。
こちらもいくつか種類があり、Markdownや、これより実用的なAsciiDocなどがあります。
また、DocBookやDITAにおいても、Simplified DocBookやLightweight DITAといった簡易な機能のものも存在します。

情報資産としての文書活用の重要性

ここまで、マークアップ言語では、効率よく見栄えのいい文書を作成できるだけでなく、タグ付けした情報を活用することで、様々な機能を効率的に実現できることをお話ししました。
しかしマークアップ言語で実現できるのは、技術文書作成の効率化だけではありません。
技術文書は様々な情報が蓄積された、いわば情報資産です。
マークアップ言語で作成した技術文書をPDFだけでなくHTML形式でも出力してWebで公開し、何を読まれているかアクセス解析した結果をもとに製品／サービスの改善や、訴求などマーケティングに活用するといった例は多いと思います。
それだけでなく、マークアップ言語で無駄なく整理された情報は、データ分析等のデータ活用にも向いています。
例えば、お問い合せ情報をマークアップ言語で整理・文書化し、それをデータ分析することで潜在化されたニーズや課題を引き出すにも有効です。

導入に向けての行動

では自分が関わるプロジェクトや業務では、どのマークアップ言語を採用すればよいでしょうか。
それは、作成する文書の特性や、文書のどのような情報を活用したいのかによって異なります。
マークアップ言語に限った話ではないですが、夢のような仕組みと過信して、導入したものの、うまく仕組化できず失敗に終わるケースも見受けられます。

実際に弊社では、技術文書作成を効率化したい、とご相談を受けて、どのような文書を作成し、どのように文書情報を活用したいか等を、お聞きした上で、最適な仕組みをご提案しています。
現状の文書作成を効率化したい、マークアップ言語を導入済みだけどさらに効率化したい、とお考えの場合は今一度、これらを整理し直すと良いでしょう。

まとめるとこういうことです。

効率化やその先のデータ活用をも見据えた技術文書作成のあり方として、参考にしてみてください。