JaSST '22 Tokyoのセッションの中で、『プレスマンの白本』*1の「21.12 ドキュメントとヘルプ機能のテスト」で言及されている、「ドキュメントテスト」*2についてお話しました。
なおこの用語はISTQB用語集では見つからない*3 のですが、プログラムそのものと一緒に提供されるドキュメントに対するテストを意味しています。リリースノートや製品マニュアル*4などが対象になりますが、この記事ではマニュアルのテストについて書いていきます。
ドキュメントテストが難しい要因
マニュアルはユーザが直接利用するものであり、製品の一部です。そのチェックに手を抜いていいと思う人はいないでしょう。それでも、品質が十分でないマニュアルが最後の方まで残っていることがあります。
マニュアルのテストが不十分になる原因は、大きく2つあります。
- マニュアルが製品と並行して完成に近づく性質があり、最後の最後まで更新が続けられがちなので、テストを後回しにしてしまう。
- 他のテストに比べて単純で退屈に見えて、軽視してしまう。
さらに、『アクティブユーザのパラドックス』という概念があります。Nielsen氏の記事から引用してみましょう。
ユーザは絶対にマニュアルを読まない。いきなりソフトウェアを使い始めるのだ。彼らには始めようという意欲が旺盛であり、目前には片付けるべきタスクもある。システムそのものには関心がなく、事前の取り決めや設定、学習パッケージに時間を割くつもりはないのだ。
こうなると、ろくに読まれもしないドキュメントのテストの費用対効果って？と疑問に思うこともあるでしょう。
ドキュメントテストが大事な理由
では、マニュアルはいつ読まれるのか。
経験上、それは「最初の最初」と、「困ったとき」ではないでしょうか？
そんな場合にマニュアルの品質が悪いと、どうなるか。
「最初の最初」は、ソフトウェア製品でいうと「インストール」にあたります。インストール方法がわかりづらい、ましてや失敗するとあっては、どんなに魅力的な機能を謳ったところでむなしいだけです。
「困ったとき」は、その時点ですでにストレスが溜まっているわけです。イライラしているところにきて、マニュアルに沿って操作してもうまくいかない。場合によっては事態を悪化させる。不愉快の二乗です。こんな最悪なユーザ体験ってあるでしょうか。
またユーザからすると、「マニュアルに書いた通りに動く、ことすら確認していないのか、この製品は」ってなりますよね。
ユーザを助けるためにも、また信頼を失わないためにも、ドキュメントの品質はとても重要なのです。
ドキュメントテストの2つの段階
では、ドキュメントの品質はどのように評価*5するのでしょうか。
白プレでは、ドキュメントテストを2段階に分けています。
1段階目はテクニカルレビューで、ドキュメントが明確な文章であるかを確かめる。2段階目は動的テストで、ドキュメントと合わせて実際のプログラムを動かす。
マニュアルって、ユーザが直接目にするもので、つまりある種のUIなんですよね。
決められた体裁に従っているか、文章が論理的で、長すぎず、主述のねじれがなく、適切に箇条書きや図表が利用され、・・・みたいな、テクニカルライティングのお作法に沿っているか、を確認する必要があります。これが1段階目で、レビューの対象になります。
そのうえで、書かれたことが「正しい」かどうかは、テストの対象。2段階目です。
時間のない中で作られたマニュアルは、「まるっきり間違っている」よりも、「部分部分は正しい、全体としては正しくない」になりやすいように思います。あることを実現するために10ステップ必要な場合に、1～5は正しい、7～10も正しい、でも6が抜けている。みたいなイメージです。
こんなことが起こる要因にも、いくつか考えられます。
- マニュアルに載せる手順を、部分部分の切り貼りで作っている。
- 書き手が中身を知りすぎていて、暗黙のステップを飛ばしてしまう。
- いろいろと「設定済み」の開発環境で動かしているために、本来は必要な設定の手順が漏れる。
ですのでマニュアルのテストはできる限り、「そのマニュアルを作った人以外」が、「ユーザがその操作を行うであろう状態を模擬した環境」で、「手順を一気通貫して」行うのがよいと思います。
なお、ドキュメントテストを完全に独立したテストとして行うことが必須かといえば、そんなことはありません。インストールテストの中でマニュアル確認を兼ねたり、エラー系・障害系のテストでトラブルシューティングの章を検証したりというのは、悪くない作戦だと思います。
マニュアルを書くのは誰？
マニュアルを誰が書くかは、組織によっていろいろでしょう。開発者がマニュアルまで書く場合もあれば、専門のテクニカルライターがいるケースもあるでしょう。今回の記事は、どちらかといえば前者の場合に当てはまるかなと思います。
後者の場合は、開発部門とライター部門の垣根を低く、連携を密に、お互い敬意をもって、みたいなコミュニケーション上の留意事項も出てきます。
ともあれ、「ユーザによって読みやすい文章を書ける」というのはプロフェッショナルのスキルであり、それがしっかりできるテクニカルライターさんには敬意を感じます。
"books" by whereisyourmind is licensed under CC BY-NC-SA 2.0
*1:『実践ソフトウェアエンジニアリング 第9版』の通称。略称は『白プレ』。
*2:なぜか資料内では「マニュアルテスト」と表現していました。これだと手動テストと混同されそうです。
*3:これをTwitterでつぶやいたところ、辰巳敬三さんが以下のように教えてくださいました。
documentation testingはGlossaryのVersion 3.1迄はあり、Version 3.2で"Not mentioned in any syllabus"という理由でremoveされています。
定義は、
documentation testing: Testing the quality of the documentation, e.g. user guide or installation guide. ドキュメンテーションテスト（documentation testing）： ユーザガイドやインストールガイドのようなドキュメントの品質をテストすること。
*4:取扱説明書、ユーザーズガイドなどと呼ばれることもありますが、以下「マニュアル」で統一しています。
*5:ドキュメントの品質の「作り込み」は、テクニカルライティングという別の分野の要素が強くなるため、この記事では触れていません。
