はじめに
弊社Works Human Intelligenceではパッケージソフトウェアの開発を行なっています。
お客様がパッケージソフトウェアの使い方を知りたいときに、まず目にするのは製品のマニュアルでしょう。せっかく便利な機能を実装しても、お客様に使い方や設定方法を理解していただけないとその機能は利用されません。
そのため、わかりやすいマニュアルを提供することは製品の価値を高める上で非常に重要です。
しかし、弊社では長らくマニュアルの品質改善が進まないことが課題となっていました。
この記事では、その課題を解決するために、弊社の製品マニュアル品質改善チームがどのように取り組んでいるのかを紹介します。
何が課題だったのか
製品ごとにマニュアルを作成するツールや運用ルールがバラバラ
マニュアルは製品ごとに異なる仕組みで管理されており、ファイルの保管場所や形式、編集方法やレビュー方法も製品ごとにバラバラになっていました。
そのため、開発者はマニュアル編集ツールや運用ルールを製品ごとに習得する必要があり、またマニュアル管理チームは全てのツールや運用ルールを習得する必要があり、学習コストやメンテナンスコストがかかっていました。
マニュアルの原本が非Plain Text形式で管理されていた
マニュアルの原本はデータベースに保存されていたり、ファイルサーバにWord形式等で保管されていました。
これらの形式だと、以下のような問題があり、生産性が非常に低い状態でした。
- 差分を簡単に確認できないため、レビューに時間がかかる
- スクリプトで機械的なチェックをすることが困難
- デザインや共通の文言を修正する場合にもファイルを一つ一つ開いて編集しなければならない
リリース頻度が低く、品質を改善しにくい
製品マニュアルは製品のリリースと同じ頻度で３ヶ月に一回リリースされていました。
製品サポートチームからマニュアルの問題が指摘された場合、たとえそれが誤字脱字等の軽微なものであっても、開発チームでチケットを起票し、イテレーションのプランニング時に取り組むかどうか決めるという業務フローになっていました。
マニュアルの修正は、機能改善やバグ修正に比べるとどうしても優先度が下がります。
そのため、工数が足りなくなった時に真っ先に延期されてしまい、なかなかマニュアルの品質が改善されないという実態がありました。
どのように解決したのか
マニュアルの作成ツールや管理方法、運用ルールを統一
マニュアルの原本は全てGitLabサーバ上のいくつかのレポジトリに分割して保管することにし、レポジトリのレイアウトや、マニュアルの形式、原本からHTML形式のマニュアルを作成するビルドフロー、編集ツール等を統一しました。
これによって開発者は一つのツール、運用ルールのみを習得すれば良くなり、管理方法が統一されたことでマニュアル管理チームのオペレーションもシンプルになりました。
また、QiitaやZennのような快適な執筆体験でマニュアルを作成できるよう、
gulp-watchやgulp-connectを組み合わせて、テキストエディタで保存した結果をブラウザ上で即時確認しながらマニュアルを作成できるプレビューツールを開発しました。
マニュアルの原本をMarkdown形式で管理
マニュアルをMarkdown形式で記述するようにし、Pandocを用いてHTMLマニュアルを生成するようにしました。Markdown形式はPlain Textとして扱えるのでGitLab上で差分を簡単に確認することができるようになり、textlintでの日本語表現の自動チェックを行えるようになりました。
さらに、Markdown形式にしたことで、マニュアルのコンテンツとデザインを分離することができ、デザインの改善やWebマニュアルとしての機能追加（目次機能やセクション単位でのリンクのコピー等）、共通の文言修正を簡単に実施できるようになりました。
マニュアルを日次リリースし、開発以外でも改善できるように
マニュアルのリリースフローを完全自動化し、レポジトリのデフォルトブランチにコミットした修正が翌日には本番環境にデプロイされるようにCI/CDを整備しました。
これまで開発チームがチケットベースで管理していた修正依頼についても、
- サポートチームのメンバーがIssueを起票
- サポートチームあるいは開発チームがマージリクエストの形で修正案を作成
- 開発チームはマージリクエストをレビューしマージ
という運用に変えたことで、修正依頼が数時間〜数日で解決されるようになりました。
マージリクエストの作成やレビューの負荷をなるべく下げるため、Markdownの差分確認に加え、CIでビルドしたHTMLマニュアルを社内ネットワークからブラウザ上で閲覧できるようにしたり、自動チェックツールをCIで実行し、基本的な問題がないことを確認した上でレビューできるようにしました。
苦労したところ
膨大な数の既存マニュアルの変換作業
さて、このプロジェクトを成功させるには既存のさまざまな形式のマニュアルをMarkdown形式に変換する必要がありました。マニュアルの総数は実に三千ファイル以上にのぼり、機械的な変換も完全ではないため手作業での修正が必要でした。
さらに、マニュアルの変換作業中が長引くと、その間に行われたマニュアルの修正を新マニュアルに反映する作業が大変になります。そのため、３ヶ月という短期間で全マニュアルを変換する必要がありました。しかし開発チームでは通常の開発業務もこなさなければならず、変換作業の工数を確保することは困難でした。
そこで、以下のような工程に分けて手順書を作成し、変換作業を外注することにしました。
- 既存のマニュアルからテキスト抽出
- 既存マニュアルから図表の切り出し
- 見出しや箇条書き等の整形
- 図表の差し込み
変換作業は外注可能でしたが、最終的な検品作業は開発チームで担当してもらわなければなりません。
開発チームとの工数調整をして検品を進め、大きな差戻なく納期通りに変換作業を完了することができました。
既存の表現をMarkdownで実現可能な表現に統一するガイドラインづくり
実際に移行作業を進めてみると、Markdownでは容易に表現できない記載内容が見つかりました。例を挙げると、
- テーブルのセル結合
- 図表に吹き出しがついている表現
- 改行や空白文字を用いたレイアウト
- 文字色をさまざまに変えた表現
- 「コラム」のような本来の文章構造から独立した節
などなど。
これらをアドホックに対応するという選択肢もありましたが、そうするとマニュアルデザインの統一感が薄れ、デザインの一括変更が難しくなってしまいます。
そのため、なるべくMarkdownで表現可能な方法で似たような表現がないかを模索し、代替案を提案しました。その上で、どうしても必要なものはCSSでデザインを作成し、どのような記法にするかガイドラインに記述していきました。
まとめ
製品マニュアルは製品の使いやすさを向上させる重要な要素の一つですが、エンジニアは文章を書くプロではありません。また、コード修正に比べて相対的にマニュアル作成に工数を割くことも難しいです。
そのため、マニュアル作成・管理にかかるコストの高さは、マニュアルの品質や更新頻度の低さの原因になっていました。
今回の取り組みによって、マニュアルの執筆体験やレビュー負荷を改善することで、短時間で品質の高いマニュアルを作成することが可能になりました。
また、リリース頻度を増やし、開発者以外でも修正の提案をできるようにしたことで、マニュアルを見返して分かりにくいところに気づいた人がすぐ修正するようになり、マニュアルの品質が継続的に改善されるようになりました。
マニュアル改善チームでは今後も製品マニュアルの品質を改善するための取り組みを進めていきます。
最後まで読んでいただき、ありがとうございました。