使い方を広める技術調査の型
技術調査は、業界経験の長短にかかわらず「かかる時間」「仕上がりの解像度」「理解しやすさ」に大きな差が生まれます。差が生まれる要因は、調査対象を使ってどうなりたいのか、ドキュメントにどのような内容が必要なのか、どのような進め方をすればスムーズなのか、をどれだけ理解しているかです。
調査の目的によって構成や進め方は変わってきます。ここでは、使い方を広めるための技術調査の進め方を整理してみます。
想定する状況
調査対象はソフトウェア（SaaS, パッケージソフト, コマンド, ライブラリなど）
技術選定は終わっている（おそらく別のメンバーが実施済み）
「どう使うのか」を整理して、みんなが使えるようにするタイミング
前提知識
■章立てのテンプレート
経験上、必要になるのはこの構成が多いです。目的や調査対象に合わせて不要なセクションを削除し、想定するユースケース（用途）に合わせて書き足していきます。
## システムコンテキスト
※調査対象がユーザーからどう見えるのか、どこで動くのか、何と関わるのかを図解。
## 概念構造
※使うときの地図
※調査対象が定義している用語群の所有関係、つながり方を図解。
## ユースケース
※用途ごとに、使い方・見え方を整理。
## （管理する定義や設定がある場合）定義・設定のライフサイクル
※git管理できるからブランチ運用をどうする、画面で変更するからどんなルールにするなどを整理。
- 管理が必要な定義・設定
- ライフサイクル
- 追加
- 更新
- 削除
## （管理する実行環境がある場合）システムアーキテクチャ
※運用者からどう見えるのか、構築・運用する要素はどれだけあって、どう関わるかを図解。
## （管理する実行環境がある場合）運用
- 新規構築
- モニタリング
- バージョンアップ
- 定期的に実施が必要なこと
■調査全体のアプローチ
●各ステップで立ち止まり、見渡してから進む
技術調査は、あいまいな地図で目的地まで到達する旅のようなものです。目的地を間違えれば価値はなく、道を間違えれば時間を浪費します。途中で道がなくなってしまうことさえあります。
調べるルートはどんなものがあるのか？どのルートが最短か？行き詰まったら、どんな代替ルートがあるか？を見渡してから進みましょう。
●汎用か専用かで、一次情報を読む「順番」と「範囲」を変える
技術調査で最も信頼できる、誤りが少ない情報は、開発元が出している一次情報です。検索でヒットした記事を無策で読んでいくだけでは、古いバージョンだったり、筆者の誤解があったり、目的と異なる使い方だったりします。一次情報を軸にして、二次情報をうまく組み合わせてメンタルモデルを固めていきます。
専用ソフトの場合
一次情報 → ユースケースがマッチする事例
信頼度の高い情報で総量を把握した後、うまい使い方を知る流れが最もスムーズです。
汎用ソフトの場合
ユースケースがマッチする事例 → 一次情報の抜粋
public cloudやofficeなど多機能なソフトの場合、公式ドキュメントの記載はできることの全量が記載されているので、順に読んでも何ができるのかを捉えることは難しいです。これはプロダクトの特性を考えると仕方がないことです。範囲を絞っておおまかに理解 → 範囲を絞って詳細を把握する流れがスムーズです。
●ドキュメントがないなら試してまとめる
ドキュメントが整っているということは、開発が落ち着いて、ユーザーを増やすフェーズに入っているということです。もう少し早いフェーズのものを採用する場合は、ドキュメントは整っていません。また、多くの場合、使い方のマニュアルはあっても、構成やトラブルシューティングのような情報は用意されていないことが多いです。
調査対象を使える人を増やすことが目的の場合、ドキュメントがないなら自分たちでつくり、使う人達の中で共通のメンタルモデルをつくる必要があります。
自分たちでドキュメントをつくるのなら、想定するユースケースの使い方に絞って試すのがスムーズです。使う側の立場で見える構造や、対象が扱う概念のつながりを整理しましょう。
●使うために必要十分な解像度を探す
調査する対象を、決められた手順で使うだけなのか、構造を理解してうまく活用するのか、組織の状況に合うように保守するのか、内部構造を理解して稼働を安定させるのか、用途や役割によって必要な解像度は違います。
誰にどの解像度で届けるのが、よりスムーズになるのかを探しながら調査を進めましょう。
●文章はテクニカルライティングで整える
基本的にドキュメントは読んでもらえません。読んでもらえたとしても、必要な箇所だけだったり、さっと読み流されてしまうことがほとんどです。
少ない機会で、できるだけ共通のメンタルモデルをつくるためには、シンプルな文章が必要です。テクニカルライティングの手法に従って、読み手がメンタルモデルを作りやすくなるように心がけましょう。
■調査の進め方
●目的とユースケースの把握
まずは調査を進める方向を把握しましょう。方向を間違えれば、進めた調査の多くがムダになり、大きな手戻りにつながります。これから手を付ける膨大な調査範囲から、範囲を絞り込む指針にもなります。
この調査対象を使ってどうなりたいのか？
この調査対象がどうして選ばれたのか？
どんな使い方を想定しているのか？
調査にかけられる時間は有限です。方向と合わせて、調査をどこまで進めるのかの距離感を把握しましょう。使うタイミングでドキュメントが整っていなければ元も子もありません。
明日、作業を依頼するために手順だけがほしい。3日後に、チーム内で使い始めるために、使う立場での情報を整理したい。1ヶ月後にユーザー提供するために網羅的な資料がほしい。それらを段階的に進める状況かもしれません。いつ、何をするために必要なドキュメントなのかを把握しましょう。
●章立ての仮置き
調査対象に定義や設定の管理が必要か、実行環境の管理が必要かで、必要な情報は大きく変わります。使い方を広めることが目的なので、ユースケースを実現する操作説明のボリュームが一番大きくなります。章立てを仮置きして、つくるものの全体像をイメージしましょう。
章立てのテンプレートから、調査する対象に合わせて不要な部分を削る
把握したユースケースごとに使い方を記載する枠を用意する
●情報源を把握
調査を始める前に、情報がどのくらいあるのかを把握しましょう。どこに、どんな情報が、どれだけの量あるのか、情報源の概観を知っておくことで調査の流れをスムーズにできます。
ルール
・「目次 or 見出し」と「図・表」だけをざっと流し見る
・目安は 1ページ 3分未満
把握の流れ
・一次情報(公式ドキュメント)の把握
・よくある構成のどこまで揃っているか？
・概要
・内部構造
・用語
・インストール方法
・設定方法
・Getting Started
・機能別のマニュアル
・その情報は、どのバージョンか？
・二次情報(記事やスライド)の把握
・バリエーションはどのくらい満たされているか？
・概要の紹介
・機能の紹介
・特定ユースケースでの使い方
・トラブルシューティング
・deep dive
・その情報は、どのバージョン（いつ書かれた）か？
・その情報は、信頼できそうか？
●ユースケースを実現できそう？
ここまでで調査対象のことをざっくり把握できていると思います。この時点で、立ち止まって、想定しているユースケースが実現できそうか、考えてみましょう。
もしかしたら、想定がずれていて、この調査対象ではユースケースが実現できないのかもしれません。それなら他の候補に変更するでしょう。思ったほどやりたいこととマッチせず、使い方を限定的にするかもしれません。
ここまでで、実現するイメージが沸かないのであれば、この時点で相談しましょう。目的やユースケースを取り違えているのかもしれません。調査した資料は、相談中にすぐ表示できるように準備しておいてください。
●調査のステップを整理
実現するイメージが湧いたのなら、一度立ち止まって、調査のステップを整理しましょう。作業完了までの流れを把握します。
章立てのセクションにどの情報がマッチしそうか、を仮置き
マッチする情報がないのはどこか、を仮置き
マッチするものがないのであれば、試して分かったことをまとめます
多くの場合、システムコンテキストや概念構造の情報はないので、動かさないと把握できません
さくっと動かせない場合は、すぐに相談しましょう
情報整理でとどめたり、別の選択肢に切り替えるかもしれません
調査のステップを分ける
章立てを上から順にまとめる
一次情報からまとめる
二次情報からまとめる
※調査対象によっては順番が入れ替わります
動かさないとわからないことを埋める
使えるようにする
ユースケースを試す
わかったことをまとめる
さっと動かせるかの判断基準サンプル
・SaaS：試せる環境があるか？
・無料プラン
・試用期間
-- これ以降は相談 --
・問い合わせが必要
・パッケージソフト：ローカルで起動できるか？
・SaaS版 無料プラン or 試用期間
・container
・k8s
・installer
-- これ以降は相談 --
・buildが必要
・コマンド：ローカルで起動できるか？
・package manager
・install手順
-- これ以降は相談 --
・buildが必要
・ライブラリ：試すプロジェクトをすぐに用意できるか？
・既存プロジェクトのtest
・公式サンプル
-- これ以降は相談 --
・自前でサンプルプロジェクトの作成が必要
●期日までに終わる？
完了までの流れが捉えられたら、一度立ち止まって、各ステップの規模を考えましょう。どこが難しそうですか？どれくらいの時間がかかりそうでしょうか？期日までに終わらないなら、すぐに相談しましょう。
時間がかかるステップをあとに回して、段階的に進めるかもしれません。急いでいないので、期日を後ろに倒すかもしれません。
●まとめながらステップを進める
調査の中でメンタルモデルの解像度が上がっていきます。捉えた内容をoutputに書き起こしながら調査を進めましょう。読み進んで・動かしてみて理解が深まったなら、すでに書いた内容をブラッシュアップすれば良いのです。
「情報をすべて読んでからの方がきれいにまとめられる」と考えているなら、それは幻想です。絶対に避けましょう。書き起こさずに読み進めるとさまざまな問題を引き起こします。
メンタルモデルのヌケモレや不整合、方向性のズレなどに気付けない
把握したが忘れてしまい、もう一度把握しなおすことに
導入に向けた致命的な問題に気づいても、説明できない
割り込みが入って、ゼロからやり直し
●目的・ユースケースを実現できた？
動かしてみた結果、ユースケースを実現できなかったのなら、すぐに相談しましょう。
もしかしたらユースケースを捉え間違えていたのかもしれません。調査対象を使ってどうなりたいのか？は、別な使い方でも実現できるかもしれません。
●説明の素振り
全体を書き終えたのなら、想定読者・レビュアの前で説明するつもりで、声に出してリハーサルしてみましょう。実際の説明の場を想像すると、つくるときとは別の客観的な視座で、様々な気づきを得られます。
わかったつもりが、説明できない
わかっているのに、書いていなかった
知らない人には、この順番では意味がわからない
など
●解像度は十分？
素振りの結果、目的とユースケースを実現するのに十分な解像度になっていましたか？
深さ、広さ、構造、時間の軸で見直してみると、ヌケモレ、表現や粒度のゆがみなどに気づくことができます。
自力で解消できそうなら、この進め方の最初「目的」から見直してみましょう。目的から外れた部分にゆがみが出ていることはよくあります。バッサリ削除し、ナレッジとして別の場所に残すだけで済むかもしれません。
違和感があっても解消方法が見えないのであれば、すぐに相談しましょう。outputを埋める形でまとめてきているので、相談もスムーズになっているはずです。
●文章を滑らかにする
ここまでに何度か見直してはいますが、一人でまとめているので、どうしても自分の解釈が挟まっています。出来上がったメンタルモデルの説明を受けるなら、長い複雑な文でも内容を捉えられます。これからメンタルモデルを組み立てる場合、理解しやすい構成・シンプルな図解と合わせて、短く単純な言葉を積み重ねていくしか方法はありません。
自分の解釈から離れるために、テクニカルライティングができているかという観点で、つくったものを見直してみましょう。
■まとめ
技術調査で大きな差が生まれる「かかる時間」「仕上がりの解像度」「理解しやすさ」を捉えるために、使い方を広める状況を例にして、ドキュメントにどのような内容が必要なのか、どのような進め方をすればスムーズなのかを紹介しました。
調査対象を使ってどうなりたいのか、どんな使い方を想定しているのかを正しく捉えられれば、展開しやすいドキュメントを型にはめてつくることができます。
調査をスムーズに進める肝は、立ち止まって見渡すことです。広大な調査範囲から、ゴールまでの最短ルートを、全速力で駆け抜けるには、区切りごとに立ち止まる必要があるのです。気になることは、すぐに知りたくなるのが人のサガ。とてもよく分かります。気になることが出てきたなら、メモを残して進みましょう。ゴールに到達した後で調べれば良いのです。
次回は、この流れに沿って調査を進めるサンプルです。
いつも応援していただいている皆さん支えられています。