マニュアルレボリューション〜楽しく書ける製品マニュアルを目指して〜


# はじめに
弊社Works Human Intelligenceではパッケージソフトウェアの開発を行なっています。

お客様がパッケージソフトウェアの使い方を知りたいときに、まず目にするのは製品のマニュアルでしょう。せっかく便利な機能を実装しても、お客様に使い方や設定方法を理解していただけないとその機能は利用されません。
そのため、わかりやすいマニュアルを提供することは製品の価値を高める上で非常に重要です。

しかし、弊社では長らくマニュアルの品質改善が進まないことが課題となっていました。
この記事では、その課題を解決するために、弊社の製品マニュアル品質改善チームがどのように取り組んでいるのかを紹介します。

# 何が課題だったのか

## 製品ごとにマニュアルを作成するツールや運用ルールがバラバラ

マニュアルは製品ごとに異なる仕組みで管理されており、ファイルの保管場所や形式、編集方法やレビュー方法も製品ごとにバラバラになっていました。

そのため、開発者はマニュアル編集ツールや運用ルールを**製品ごとに習得**する必要があり、またマニュアル管理チームは**全てのツールや運用ルール**を習得する必要があり、学習コストやメンテナンスコストがかかっていました。

## マニュアルの原本が非Plain Text形式で管理されていた

マニュアルの原本はデータベースに保存されていたり、ファイルサーバにWord形式等で保管されていました。

これらの形式だと、以下のような問題があり、生産性が非常に低い状態でした。

- **差分を簡単に確認できない**ため、レビューに時間がかかる
- スクリプトで**機械的なチェックをすることが困難**
- デザインや共通の文言を修正する場合にもファイルを一つ一つ開いて編集しなければならない

## リリース頻度が低く、品質を改善しにくい

製品マニュアルは製品のリリースと同じ頻度で３ヶ月に一回リリースされていました。

製品サポートチームからマニュアルの問題が指摘された場合、たとえそれが誤字脱字等の軽微なものであっても、開発チームでチケットを起票し、イテレーションのプランニング時に取り組むかどうか決めるという業務フローになっていました。

マニュアルの修正は、機能改善やバグ修正に比べるとどうしても優先度が下がります。
そのため、工数が足りなくなった時に真っ先に延期されてしまい、なかなかマニュアルの品質が改善されないという実態がありました。

# どのように解決したのか

## マニュアルの作成ツールや管理方法、運用ルールを統一

マニュアルの原本は全てGitLabサーバ上のいくつかのレポジトリに分割して保管することにし、レポジトリのレイアウトや、マニュアルの形式、原本からHTML形式のマニュアルを作成するビルドフロー、編集ツール等を統一しました。

これによって開発者は**一つのツール、運用ルールのみ**を習得すれば良くなり、管理方法が統一されたことでマニュアル管理チームのオペレーションもシンプルになりました。

また、QiitaやZennのような快適な執筆体験でマニュアルを作成できるよう、
[gulp-watch](https://www.npmjs.com/package/gulp-watch)や[gulp-connect](https://www.npmjs.com/package/gulp-connect)を組み合わせて、テキストエディタで保存した結果を**ブラウザ上で即時確認しながらマニュアルを作成できるプレビューツール**を開発しました。

![previewtool.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/67228/288e205d-1d7b-5a9d-68eb-4f65ee74f3ff.gif)


## マニュアルの原本をMarkdown形式で管理

マニュアルをMarkdown形式で記述するようにし、[Pandoc](https://pandoc.org/)を用いてHTMLマニュアルを生成するようにしました。Markdown形式はPlain Textとして扱えるのでGitLab上で**差分を簡単に確認**することができるようになり、[textlint](https://github.com/textlint/textlint)での**日本語表現の自動チェック**を行えるようになりました。

さらに、Markdown形式にしたことで、マニュアルの**コンテンツとデザインを分離**することができ、デザインの改善やWebマニュアルとしての機能追加（目次機能やセクション単位でのリンクのコピー等）、共通の文言修正を簡単に実施できるようになりました。

## マニュアルを日次リリースし、開発以外でも改善できるように

マニュアルのリリースフローを完全自動化し、レポジトリのデフォルトブランチにコミットした修正が**翌日には本番環境にデプロイされる**ようにCI/CDを整備しました。
これまで開発チームがチケットベースで管理していた修正依頼についても、

1. サポートチームのメンバーがIssueを起票
1. サポートチームあるいは開発チームがマージリクエストの形で修正案を作成
1. 開発チームはマージリクエストをレビューしマージ

という運用に変えたことで、修正依頼が**数時間〜数日**で解決されるようになりました。

マージリクエストの作成やレビューの負荷をなるべく下げるため、Markdownの差分確認に加え、CIでビルドしたHTMLマニュアルを社内ネットワークから**ブラウザ上で閲覧**できるようにしたり、**自動チェックツールをCIで実行**し、基本的な問題がないことを確認した上でレビューできるようにしました。

![Untitled Diagram.drawio (3).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/67228/487e32ab-dd26-8806-7605-c6e3cb84ed7f.png)


# 苦労したところ

## 膨大な数の既存マニュアルの変換作業
さて、このプロジェクトを成功させるには既存のさまざまな形式のマニュアルをMarkdown形式に変換する必要がありました。マニュアルの総数は実に**三千ファイル以上**にのぼり、機械的な変換も完全ではないため**手作業での修正**が必要でした。

さらに、マニュアルの変換作業中が長引くと、その間に行われたマニュアルの修正を新マニュアルに反映する作業が大変になります。そのため、**３ヶ月という短期間**で全マニュアルを変換する必要がありました。しかし開発チームでは通常の開発業務もこなさなければならず、変換作業の工数を確保することは困難でした。

そこで、以下のような工程に分けて手順書を作成し、変換作業を外注することにしました。

1. 既存のマニュアルからテキスト抽出
1. 既存マニュアルから図表の切り出し
1. 見出しや箇条書き等の整形
1. 図表の差し込み

変換作業は外注可能でしたが、最終的な検品作業は開発チームで担当してもらわなければなりません。
開発チームとの工数調整をして検品を進め、大きな差戻なく納期通りに変換作業を完了することができました。

## 既存の表現をMarkdownで実現可能な表現に統一するガイドラインづくり

実際に移行作業を進めてみると、Markdownでは容易に表現できない記載内容が見つかりました。例を挙げると、

- テーブルのセル結合
- 図表に吹き出しがついている表現
- 改行や空白文字を用いたレイアウト
- 文字色をさまざまに変えた表現
- 「コラム」のような本来の文章構造から独立した節

などなど。

これらをアドホックに対応するという選択肢もありましたが、そうするとマニュアルデザインの統一感が薄れ、デザインの一括変更が難しくなってしまいます。

そのため、**なるべくMarkdownで表現可能な方法で似たような表現がないかを模索**し、代替案を提案しました。その上で、どうしても必要なものはCSSでデザインを作成し、どのような記法にするか**ガイドラインに記述**していきました。

# まとめ

製品マニュアルは製品の使いやすさを向上させる重要な要素の一つですが、エンジニアは文章を書くプロではありません。また、コード修正に比べて相対的にマニュアル作成に工数を割くことも難しいです。
そのため、マニュアル作成・管理にかかるコストの高さは、マニュアルの品質や更新頻度の低さの原因になっていました。

今回の取り組みによって、マニュアルの執筆体験やレビュー負荷を改善することで、**短時間**で**品質の高い**マニュアルを作成することが可能になりました。
また、リリース頻度を増やし、開発者以外でも修正の提案をできるようにしたことで、マニュアルを見返して分かりにくいところに気づいた人がすぐ修正するようになり、マニュアルの品質が**継続的に改善**されるようになりました。

マニュアル改善チームでは今後も製品マニュアルの品質を改善するための取り組みを進めていきます。
最後まで読んでいただき、ありがとうございました。