ドキュメント書くのが難しいとか、どう書いて良いのかわからないのでコツを教えて欲しいという相談を時折受けるので、まとめてみました
ちょっと長めなので Index
まず忘れて欲しい事
ドキュメントを書くという事の目的
書くための基本
1.「何を伝えたいのか」をまとめる
2. 読み手を具体的にイメージする
3. 読み手に伝わる構成を考える
4. シンプルに書く
まとめ
以降は実務への適用編
「何を伝えたいのか」をまとめる
読み手を具体的にイメージする
読み手に伝わる構成を考える
シンブルに書く
「何を伝えたいのか」をまとめる
読み手を具体的にイメージする
読み手に伝わる構成を考える
シンブルに書く
まず忘れて欲しいのは「いきなり書き始める」と「起承転結」です
小学校低学年の頃に、原稿用紙が配られ「さぁ、今から昨日あった事を書いてください」ってお題が与えられ、いきなり原稿用紙に書かされましたよね
もう少し学年が進むと「起承転結」を習いましたよね
実は、この2つが「書くための基本」を台無しにする諸悪の根源なので今すぐ忘れてください
「ドキュメントを書く」と言われてどんなイメージを持ちますか?
・面倒くさい
・難しい
・何を書けば良いのかわからない
・どう書けば良いのかわからない
ドキュメントは、文字、図、表で構成されているけど、これってどういう書けば良いんだろう?
と「書き方」で色々悩んでいたりしませんか?
世の中には、文章表現テクニックを解説している本とか Web サイトは沢山あります
ショッキングステートメントとか、キャッチーなタイトルとか…
このテクニックだけで書かれているのが、情報商材とか、残念なショッピングサイトとか、bloger 上がりの残念 Web 記事とか...
よく目にしますね
中身が全くなく、「目を引く字面」だけを追い求めているアレです
大切なのは、文章表現テクニックではないです
ドキュメントを書く目的は、伝えたい事を読み手に伝える事です
ドキュメントは、書く事が目的ではありません
文章表現テクニックにとらわれて、伝えたい事を相手に伝える目的を見失っては本末転倒です
伝えたい事が直接相手の脳にダイレクトインプット出来れば良いのですが、残念ながら人の脳はそんなに便利には出来ていません
ドキュメントを書くという事は、ドキュメントを通じて伝えたい事を相手に伝える事です
つまり、ドキュメントは、限りなく薄くして(裏方に徹して)、伝えたい事を如何にストレートに相手に伝えるかが書くための基本なのです
誰しも最初は初心者です
最初から上手く書くことが出来なくても当然ですし、基本も知らず、練習せずに上達する事はありません
書くための基本は、以下の4つに尽きます
(それぞれについては後程説明します)
1 文章を書く前に「何を伝えたいのか」をまとめる
2 文章を読む人を想像して「何を期待しているのか」「何がわかっていて、何がわかっていないのか」を具体的にイメージする
3 どう伝えるのかの構成を考える
4 考えた構成に沿って、可能な限りシンプルに書く
いきなり文章を書き始めたら負けです
相手に伝わりやすい文章になるか否かは、書き始める前準備で8割が決まります
まずは「自分が何を伝えたいのか」を整理しましょう
整理には箇条書きが有効です
うまく箇条書きが浮かばない時は、伝えたいキーワードを片っ端から書き出して、ある程度書き出したら、それらをグループピングして、何を伝えたいのかを箇条書きにまとめます
ここで大切なのは「全てを伝えようとしない」事です
何が重要で、何が些細な事なのかをしっかり見極めて、伝えたい事で本当に重要な事だけに絞り込むことです
書く事が飛躍的にうまくなるブレークするポイントは「読み手を強く意識する」です
伝えたいことをいくら整理しても、読み手が期待している事と違っていたり、読み手が知らないことが前提条件になっていると、読み手にストレスかかりまくりで伝えたい事は一切相手の頭に入っていきません
このような事態を避けるために、読み手を具体的にイメージすることが大切です
具体的に個人をイメージして「〇〇さんに伝えるシチュエーション」で相手に説明する状況を想像するのが良い手です
大切な事なので繰り返しますが、飛躍的に書く事が上手くなる秘訣は、「読み手を意識する」事です
読み手の思考と認識をどれだけ意識できるかが「伝わるドキュメント」を書くための最重要ポイントです
例えば「〇〇さんに読んでもらう」といった感じで、具体的に「相手」をイメージするのがオススメです
相手が具体的にイメージ出来たら、「何に困ってドキュメントを読むのか」、「何が知りたくてドキュメントを読むのか」かを具体的にイメージします
そして、ドキュメントを読む際に「何が理解できてるのか」と「何が出来ていないのか」をイメージします
イメージが出来たら、それぞれを具体的にメモします
・何が知りたいのか/何に困っているのか
・予備知識として知っている事や、理解できている事
・理解できていない事
これで、伝えたい事と、読み手がわかったので、「伝えたい事」と「読み手」をどうつなぐと相手に伝わるのかを考える準備段階が整いました
ここでも、「読み手の思考と認識をどれだけ意識できるか」が最重要ポイントになります
効果的に相手に伝えるためのドキュメント構成には鉄板のテンプレートがあります
・タイトル
・結論
・目的/背景/課題
・論理展開
・まとめ
これらの中身を決める際に大切なことは「読み手の意識の流れ」を意識する事です
読み手が最初に目にするのは「タイトル」です
タイトルを読んで、自分の知りたい情報が得られる予感とか、困っていることが解決できる予感がしないと読んでも興味をそそりません
ここで役に立つのが、先にメモした「読み手は何が知りたいのか/何に困っているのか」です
タイトルを読んで「欲しい情報が得られる」期待が湧かないようでは、伝えるための準備段階が不足しているといっても良いでしょう
ドキュメントの構成を考える際に強く意識して欲しい事は、読み手は「何がわかっていて」「何がわかっていないか」を明確に意識する事です
予備知識が無い全く未知の単語や概念がいきなり現れて、何の説明もなく先に進んでしまうのは、読み手にとって強度のストレスになります
これは、読み手を置き去りにしてしまい、読み手の興味が一気に無くなる一番やってはいけないパターンです
まず、どう伝えれば理解しやすいのか考え、構成を組み立てていきます
構成をある程度考えるたら、「読み手は今何を期待しているか」「ここまでの説明で、読み手はどこまで理解が進んだのか」「読み手がが未知に感じるものは無いか」を常に意識して構成を考えてください
構成は目次を作る感じで、各セクションのタイトルとセクション概要を書く全体デザインです
・タイトル
一言で伝えたいことを一言で表現する
・結論
何を伝えるのかを最初に宣言し、伝えたい結論を最初にまとめる
・目的/背景/課題
何を目的にこの文章が書かれているのか
そもそも、なぜこれが必要なのか
実現するにあたり、どんな課題があるのか
これらをシンプルにまとめる(中見出しのイメージ)
ここが成否の7割を決める
・論理展開
具体的な手順とかの本文
読み手の意識の流れを意識して、読み手が未知に感じる事が無いように目次を構成する
・まとめ
結論をもういちどまとめる
全てがこのテンプレート通り必要はありませんが、基本形として身に付けてください
ケースバイケースで、もっと単純構成にするとかは十分するとかアレンジするのはアリです
(そものそも、このドキュメント自体がこのテンプレート通りではない w)
大切なのは「何を伝えたのか」「読み手は何を期待しているのか」をしっかり意識し、それを実現するために全体を構成する事です
構成が出来たら、読み手の視線になって、期待している通りの構成になっているか確認/修正をします
最初のうちは、この構成段階でレビューを受けるようにしてください
書くことに慣れてくると、ここまでステップをメモに書かなくても頭の中だけで構成できるようになります
でも、このパターンで書き慣れるまでは、面倒でも意識的にメモに書いて、各構成を整理し、必要に応じてレビューを受けるようにしてください
書くことの極意は「引き算」です
極限まで削って、どこまでコンパクトにシンプルに表現できるかを追求するのがキモです
「一言」で伝えたい事の全てが伝われは、これ以上わかりやすい事はありません
逆に1万文字以上を使って何かを伝える場合は、伝えたいことがぼやすくなります
そういった意味では、キャッチコピーは、とても良くできたドキュメンテーションだと言えます
文面を書く時は、構成に従って以下を意識して文面を作っていきます
伝えたい事を真っ先にに表現する
文面は限りなくシンプルかつ必要十分な内容にする
・「1文」は短く
・ストレートな表現にする
・ノイズは入れない(不必要な記述は削る)
・主語を略さない
・長い文とか二重否定は避ける
図表をできるだけ使う
適度に行間を開ける
大切なことは、読み手がストレスを感じず、伝えたい事がスッと頭に入ってくるようにすることです
文面を書く時は、常に読み手を意識し、論理展開は読み手の思考と認識の流れに合わせます
「読み手は今何を期待しているか」「ここまでの説明で、読み手はどこまで理解しているか」「読み手がが未知に感じるものは無いか」を常に意識して本文を組み立てます
この思考に慣れてくると、頭の中に読み手が別人格としてツッコミを入れてくれるようになります
ドキュメント書いたら、他の方にレビューしてもら「わかりにくいところ」「わかりやすいところ」を指摘してもらいましょう
セルフレビューする場合は、少し時間をおいて(例えば半日後とか)から読み直すと新鮮な目で読めてセルフレビューがはかどります
身の回りにお手本はたくさんありますので、お手本をまねるのが早道だと思います
・興味をひかれた広告
・読みやすかった Web 記事
・興味を持てた雑誌記事
・NHK の科学番組
なぜ面白かったのか、なぜわかりやすかったのかの「構造分析」をしてみると勉強になります
逆に、良くわからなかったり、興味がわかない文章とか、読んでいてストレスを感じる文章を反面教師とて分析をしてみるの面白いです
書くための基本は、以下の4つに尽きます
・「何を伝えたいのか」をまとめる
単語書き出しとグルーピングで伝えたいことを箇条書きにまとめる
・読み手を具体的にイメージする
読み手は何を期待していて、何がわかっていて、何がわかってないのかをメモする
・読み手に伝わる構成を考える
読み手の思考を意識して全体構成を目次形式にまとめる
・シンブルに書く
極意は引き算
構成を作った段階でレビューを受けるのがオススメです
ドキュメントを書きあげたら、必ずレビューを受けるようにしましょう
セルフレビューはメディアを変えると、目先が変わって第三者の目になれるのでおススメです
例えば、紙に印刷して赤ペンを持って添削するが良い手法です
時間に余裕があるのなら、翌日に見直すのもおススメです
ドキュメントはどんなに時間がたっても伝えたい事を忘れません
一方、半年1年後、下手をすると数時間数分後の自分は、伝えたい事を忘れた他人になっています
未来の自分のためにも日々のアウトプットをドキュメントに記録しておく事を強くお勧めします
文字として書く事は、論理整理にもなるので、日頃から思考整理の手法として文字として書いてまとめてみると良いです
メーカとかにサポート問い合わせる場合、口頭説明では情報が揮発してしまうので、ドキュメント(メール)にまとめて問い合わせるのが効率的です
もちろん、微妙なニュアンスとか、右も左もわからない状態では口頭ディスカッションが有効ですけどね
それでは、メーカー問い合わせの場合のドキュメントはどのように書けば良いのかを考えてみましょう
「解決策」を知りたいとは思いますが、サポートにいきなり「解決策を教えろ」と言っても話が唐突すぎて解決には至りませんね
まず整理するのは、「なぜ問い合わせをしようとしているのか」です
問合せをする理由の大半は「不明な事があるので、不明な事を知りたい」のハズです
(これ以外のパターンは各自で考えて下さい
w)
まずは、不明な事を整理します
たとえば、何かしらの検証をしているケースだと想定してみます
今回は「ドキュメント通りに検証しているが、上手くいかない」ケースで考えてみます
では、順を追って整理しましょう
・何を検証しているのか
・どうなってほしいのか
・現状はどのような状況なのか
エラーコードやスクショは有効手段
例えば、このパターンに従って、MIP の外部共有検証が上手くいかない場合でサポートに伝えたい事を整理ます
・何を検証しているのか
MIP の暗号化機能を使って、外部ユーザーに暗号化した Word ファイルの共有をする
・どうなってほしいのか
許可を与えた外部ユーザーが、MIP で暗号化した Word ファイルを読むことが出来る
・現状はどのような状況なのか
外部ユーザーが暗号化した Word ファイル開こうとすると、資格情報が要求される
Word は許可されたアカウントでログオンしている
資格情報を入力しても、Word ファイルを開くことが出来ない
(エラーのスクショは撮ってね)
ここまでで、一旦「何を伝えたいのか」は出揃った気がするので先に進みましょう
今度は、メーカーのサポートエンジニアの気持ちになって、どの様な情報を必要としているを考えてみます
メーカーのサポートエンジニアは、以下の情報を必要としています
・何をしている時に起きた問題なのか
・現状はどのような状況なのか
既に、サポートエンジニアが必要として情報は大方揃っている感じなので、状況は理解してもらえそうです
では、もう一歩踏み込んで、サポートエンジニアが置かれている状況も想像してみましょう
サポートエンジニアは、日々大量の問い合わせを捌いているので、問い合わせのバックオーダーが常にある状況になっているはずです
このため、サポートエンジニアは、バックオーダーになっている問い合わせのうち どの問い合わせから手を付けるかを決める必要があります
この時に決め手になるのが、以下のポイントです
・自分が回答できる問い合わせなのか
・業務影響が大きい問い合わせなのか
回答できなさそうな問い合わせは手を出さないですし、業務影響が大きい問い合わせは優先的に対応しなくてはなりません
バックオーダーになっている問合せは一覧になっており、「問い合わせタイトル」が表示されているはずです
であるのならば、問い合わせタイトルを見て自分が回答できる範囲なのかが一目でわかるようになっていれば、適切な担当者が拾って効率よく回答してもらえそうです
伝えたい事に無かった「業務影響」は、問い合わせ情報として追加するのが良さそうです
業務影響は、通常問合せ本文で伝えるのですが、超緊急事態の場合タイトルに[緊急]と書いておくのも良いかもしれません(乱用禁止)
状況を理解したサポートエンジニアは、解決に向け必要な情報を追加質問をします
サポートエンジニアの興味は「どのような手順で操作したのか」です
手順から状況を深堀したり、必要に応じて問題を再現し状況確認します
「どのような手順で操作したのか」の追加質問は十分想定範囲内なので、問合せストローク短縮するために「再現手順」も最初に伝えるのがおススメです
サポートエンジニアは、問題を特定するために更に試してもらいたい事とか、参考にしてもらいたい情報を伝えることも多いです
既に調べた事とか試した事を言われても時間の無駄なので、「参考にした情報(URLとか)」、「試した事」も最初に伝えるのがおススメです
これで、伝えたい事と、サポートエンジニアの事がだいたいわかってきたので、どう伝えるのかの構成(目次)を考えます
・問い合わせ概要が一目でわかる問合せタイトル
・何を検証しているのか
・どうなってほしいのか
・現状はどのような状況なのか(エラーコード、スクショ、再現手順)
・業務影響(具体的に数値化出来ればパーフェクト)
・再現手順
・参考にした情報
・試した事
この構成で問合せドキュメントを書けば、問い合わせファーストコンタクトとして必要情報はほぼ揃っているので迅速な問題解決が期待できます
構成が決まれば、後はシンプルに書くだけです
伝えたい事をストレートに、ノイズは極限まで削って書くようにすれば、ドキュメントとして書く絶対量は必要最小限になるので、書くために必要な時間も、解決までにかかる時間も大幅に節約できます
組織でミーティングは日常的に開催されていますが、議論が迷走して収集つかなくなったり、そもそも何のための会議だったっんだっけ? といった経験は誰にでもあると思います
このようなミーテイングしない秘訣は「ディスカッションのためのドキュメント」を事前に書いて、参加者全員に「論点を見える化」することです
ミーティング用のドキュメントは、読ませるためのドキュメントではなく、ミーティングの冒頭で説明をする際の補助資料なので、簡単まとめる程度で十分機能します
沢山書くと、趣旨が伝わりにくいだけではなく、本来のミーティング時間を食いつぶすことになりかねません
ボリュームの目安は...
前説は長くても5分程度
スライドにして1-2枚程度
それでは、今までテンプレート従ってまとめていきましょう
まず、ミーティングで何をするのかを整理します
情報伝達会議せであれば、「伝えるべきこと」
ディスカッションや何かを決める会議であれば、「何を議論するのか」
これらを箇条書きにして整理します
今度は、ミーティングに参加する人をイメージましょう
初めて話し合う議題であれば、前提条件のインプットが必要ですね
継続審議している議題であれば、これまでで決まっている事のサマリーがあると議論に入りやすいです
「今回のミーティングのゴールはどこにあるのか」が最初に伝えられていると、安心して議論することが出来ます
これらを踏まえ、ディスカッション ドキュメントの目次を作ってみましょう
この目次はテンプレートとして十分使えるので、毎回このパターンでまとめても良いです
・会議のタイトル
会議の目的を一言で
・背景
会議を開催するに至った議題の背景
・要求/目的
議論したい事に求められている事とか、目的とか
・既に決まっている事/前提条件
今までの議論で決まった事とか、前提条件のサマリー
・議論したい事/伝えたい事
何を決めたいのか、何を議論したいのか、議論したい事の論点を具体的に
情報伝達会議であれば、これから伝える内容のサマリー
このテンプレートに合わせ、シンプルに内容を書いてミーティングの冒頭で説明すれば、短時間で中身の濃いミーティングができると思います
情報システム屋の仕事をしていると、システムに求められていることをまとめる「業務要件」をドキュメントにまとめる事がよくあります
この業務要件を整理するすめのポイントを整理してみます
既に書くための基本は理解できていると思うので、アプローチポイントに絞った方説をします
業務要件は、こちらの伝えたい事を表現するのではなく、相手が伝えいことを言語化して共通認識としてドキュメント化することです
「業務要件」とは、業務担当者とシステム設計者がシステム化の合意形成が出来ように要件をまとめたものです
「業務要件」は、システムの言葉ではなく、「一般的な言葉」と「業務の言葉」で業務に求められている要件をまとめます
これらの要件をうけて、システムはどのようになれば良いのかをまとめたものが「業務要件」の完成形になります
平たく言うと「どう作るかは別にして、これから作るモノはこうなれば良いんですよね」と業務担当者とシステム設計者が合意出来るドキュメントが業務要件です
これがブレるとシステム実装がカオスになるので、地味ながら超重要なドキュメントだったりします
「読み手を具体的にイメージ」する際に、イメージする相手は、業務ヒヤリングしている相手ではなく、コンピューターの事はよくわからないけど、決裁権を持っている責任者をイメージすると良い感じで業務要件が出来ます
具体的に言うと、情報システムは良くわからないけど、組織/経営責任を担っている業務部門長や取締役や社長に伝えるイメージです。
これは、業務をシステム化する決裁権は、業務担当者ではなく、決裁権を持った責任者であることが一般的なので、決裁権を持っている人が腹落ちできるレベルになっていないと、プロジェクトが先に進まなかったり、後から揉める事がになりやすいからでもあります
業務担当者はシステム設計には不慣れなので、細かな軌道修正(要求が抜けていたとか間違っていた)がちょいちょい発生するのでそこはうまくかじ取りをします
ただし、業務要件レベルの根底に影響が出るような大きな軌道修正が発生した時は、業務要件に立ち戻り再度合意形成をするのが安全ですね
業務要件に「システム用語」や「システム構造」を入れることはご基本法度です
「システムは何でもできるブラックボックス」と位置付けて、中身の事はこの段階では一切考えてはいけません
ただし、インプットされていない物はアウトプットできない原則はエンジニア常識として常に頭の片隅にはおいておく必要はあります
あくまで「普通の言葉」で書いた「ブラックボックスを外側から見た仕様」を言語化する事に徹する事です
ありがちなミスが、当たり前のことが書かれておらず、それが原因で致命的なトラブルが起きるケースはとても多いので、「当たり前のこと」も必ず言語化してドキュメントに書く事が鉄則です
ここを疎かにすると、業務担当者と本質的な部分の齟齬が起きている事に気が付かなかったり、業務知識が足りていないシステム担当者が参画してアサッテの方向に走ってしまったり... (黒歴史は繰り返される)
業務要件は、あくまで利用者/要求者の視線で要求をまとめたものです
業務要件には2つの側面があります
その1つ目が、業務は何を要求しているかの「業務要求」です
この段階でシステムは一切顔を出しません
人がどのような業務をしているかをまとめたものです
2つ目は、システムはどうなればいいのかの「システム要件」です
これは、業務をシステム化するために、システムにはどのような機能が必要なのかをまとめたものです
業務要求を言語化してまとめます
・組織や業界そのもの
そもそもの前提条件(権限とかセキュリティとか)
・業務全般
なぜシステムにしたいんでしたっけ? ← これがゴールを現わしている
業務全般を簡潔に説明すると
業務に関係する人物金
この業務はどうなってほしいのか?
どんな業務があるか
業務の単位(販売とか、棚補充とか)がシステム UI (機能単位)
→ 各業務の洗い出し
・各業務に対する要求
該当業務についての全般説明
該当業務に関係する人物金
権限とかセキュリティとか
この業務単位どうなってほしいのか
業務要求が揃ってきたら、非機能要求はシステム設計者が考えます
「これから作るモノはこうなれば良いんですよね」を言語化してまとめます
Copyright © MURA All rights reserved.