テクニカルトレーナーのドキュメント作成術
皆さんこんにちは。国井です。
私はマイクロソフト認定トレーナーとして20年以上に渡ってトレーニングに携わるかたわらで10冊以上の書籍や数え切れないほどの雑誌連載/Web記事を書いてきました。
一方でテクニカルトレーナー（←今までITトレーナーという呼び方をしていたんですがテクニカルトレーナーのほうが一般的な呼称のようなので、こちらで統一します）のあいだではこんな話をよく耳にします。
話せるけど書けない
今日は神が降りてこない
挙句の果てに「話せる技術と書く技術は別の能力」と言い出す人までいるのですが、言語化という観点で言えばどちらも同じ話で、ちょっとしたテクニックがあるだけで誰にでもできるものだと思うのです。だってテクニカルドキュメントであれば、村上春樹のような文章を書けと言っているわけではないし、詩的な表現など皆無なのです。ルールを定めてそれに従って書いていけば良いだけの話なので、今日はそのルールについて書いてみます。（ちなみに下記で紹介する記事の編集を担当してくださっている方曰く「国井さんの文章は見ればすぐにわかる」というほどクセの強いものだそうです。だから私の言ってることが正しいかどうかはわかりませんｗ ただ20年のあいだ編集担当の方にポイされなかったということは間違ってなかったのかなと認識してます）
ここでは私が過去に書いたドキュメントを参考にしながら、私だったらどうやってテクニカルドキュメントを書いているかを紹介します。
1. ドキュメントの設計図を書こう
そもそもテクニカルトレーナーにテクニカルドキュメントを書いてほしいと依頼する人が望むことってなんでしょうか？私はわかりやすさだと思っています。企業公式のドキュメントだと堅苦しくて読みづらいから国井さんお願い！こんな感じではないかと推察しています。
じゃあ、わかりやすさって何でしょうか？その答えはいろいろあるでしょうが確実にいえることは文章が構造化されていることです。
ということでドキュメントを書くときに最初に行うことはそのドキュメントで何を書くか？について全体像を構築することです。慣れてくれば自分の頭の中で構築できるものですが、それができない人は設計図を書きましょう。例えば上記の記事であればこんな感じの設計図になると思います。
Active Directory（以下AD）とAzure ADって何が違うの？という説明として次の3部（ここではパラグラフと呼ぶことにします）にわけて説明しています。
a. ADじゃなくAzure ADな理由
b. Azure ADでできること
c. Azure ADが他と異なる点
私のイメージとしてはa.のパラグラフ で「何が違うの？」を簡潔に説明。b.のパラグラフでAzure ADそのものの特徴を説明。c. のパラグラフはQ&Aコーナー。こんな感じです。ひとつずつ見ていきましょう。
2. 最初のパラグラフは簡潔に説明
この説明で大事なポイントは簡潔であることです。「〇〇とは？」とか「〇〇と××の違い」みたいな説明をするのに、ひたすら文章を読まないとその結論がわからない文章って読みたくないですよね？だからできるだけ簡潔に説明します。ちなみに私はADとAzure ADの違いをこんな感じでまとめています。
Azure ADは「Active Directoryのクラウド版」ともいえるサービスなのである。
この説明って本当にADとAzure ADの違いを知っている人であればツッコミどころ満載の一文だと思います。だけど私はこれでよいと思っています。
わかりやすい文章に厳密さは必要ないからです。
Azure ADにはAzure ADアプリケーションプロキシという機能があって、それを使えばオンプレミスのWebサーバーとも連携できるとしましょう。そうすると、さっきの文章はこうなります。
Azure ADは「Active Directoryのクラウド版」ともいえるサービスなのである。ただしAzure ADではAzure ADアプリケーションプロキシという機能があり、例外的にオンプレミスとも連携できるのでその点は注意したい。
おお、わかりにくくなりましたねｗ
さらにf5のソリューションと組み合わせればWeb以外のサービスとも連携できるなんていう例外があるので、それも追記しなきゃ！そしたら
Azure ADは「Active Directoryのクラウド版」ともいえるサービスなのである。ただしAzure ADではAzure ADアプリケーションプロキシという機能があり、例外的にオンプレミスとも連携できるのでその点は注意したい。さらにf5などのソリューションと組み合わせることによるオンプレミスのファイルサーバー等へのアクセスできる例外もある。
もはやコトの本質がなんだかわからなくなってしまいましたね。
だから多少の正確さを欠いたとしても文章はできるだけシンプルに。
これが最初のパラグラフで注意すべき点です。
3. 第2パラグラフでは一番説明したいことを丁寧に解説
3つに分けたパラグラフの第2パラグラフはメインの部分なので、一番説明したいことを持ってきます。ここで説明したいことは「ADとAzure ADの違い」です。しかし、最初のパラグラフですでに「Azure ADはActive Directoryのクラウド版」という結論を言っているので、次のパラグラフではクラウド版になると具体的にどんな違いがあるのか？を説明しています。ここでは具体的な違いを説明するためにAzure ADそのものの要素を最初に説明しています。
Azure ADはクラウドアプリケーションに対するSSO機能を実現するが、そのためには「認証と認可」、そして多くのクラウドアプリケーションと連携できるようにするための「アプリへのアクセス」機能が求められる。
Azure ADの機能は認証・認可・アプリへのアクセスの3つだ！と言い切っています。繰り返しますが、わかりやすい文章に厳密さは不要です。そして3つの要素に分けたら、ひとつずつの要素の中の、さらに細かい要素にわけてそれぞれの要素を簡潔に説明しています。例えば、認証という要素の中にある細かな要素としてユーザー/グループの管理と多要素認証があると触れ、それぞれについてはこんな感じで説明しています。
■ユーザー／グループの管理
認証やアクセス許可（認可）を制御するためのベースとなるユーザー／グループの管理機能を提供する。
■多要素認証
Azure ADの認証はパスワードだけでなく、電話やSMS（ショートメッセージサービス）、ワンタイムパスワードなど、複数の要素を組み合わせて認証を行う「多要素認証」をサポートする。
「ユーザー/グループの管理」についてはADとの違いを触れていないので特に違いはないよと暗示し、「多要素認証」については「Azure ADの認証はパスワードだけでなく...」と書き出すことで違いを説明しています。「ADでは〇〇なのに対してAzure ADでは××です」という書き方でもよかったと思いますが、同じ文章が何度も繰り返されるのが嫌だったので敢えて避けました。
ここまででお気づきかもしれないですが、ひとつひとつの説明したい内容に対して長い文章を一度も書いていないことがわかります。シンプルすぎる文章だとバカにされるのではないか？幼稚な印象を受けるのではないか？と思われるかもしれませんが、テクニカルドキュメントで重要なことはわかりやすさです。
わかりやすさはシンプルであること、設計図に沿った構造的な構成であること（むちゃくちゃなパラグラフ構成でないこと）だと私は理解しています。
だからこそ、ひとつの文は3行を超えないように文章を書きますし、最初に文章の設計図を描くことをするのです。
4. 最後のパラグラフは振り返りを
今回サンプルで用意したドキュメントでは最後のパラグラフはちょっと変わった終わり方をしています。Azure ADそのものの説明をここまでしてきたので、最後によく間違えやすいもの、よく質問で聞かれることを最後にまとめて紹介するという終わり方をしています。
これはこれでアリだと思って書いたのですが、一般的に最後のパラグラフでは、ここまでの文章で書いてきたことの振り返りをします。今回紹介した記事の最後の振り返りを書くとしたら、こんな感じかな。
ここまでActive DirectoryとAzure ADの違いについてみてきた。Active Directoryはオンプレミスの認証・認可のサービスとしてこれまで活躍してきたが、近年ではクラウドサービスを利用する企業も増えている。だからこそクラウドの認証・認可のサービスを提供するAzure ADの重要性が増してきているのである。
AD＝オンプレミスの認証・認可、Azure AD＝クラウドの認証・認可という振り返りをしつつ、ちょっとだけ自分の意見（「Azure ADの重要性が増してきている」と書いた部分）を付け加えて終わっています。テクニカルドキュメントを書いていると自分の意見を表明したくなると思うのですが、できるだけ「事実」と「自分の意見」はごっちゃにならないようにしたほうが誤解を招きにくくなります。だから私の意見表明は最後のまとめにできるだけ書くようにしています。
参考までに今回取り上げている記事のシリーズでちょうどよいまとめを書いている記事があったので紹介します。
ここまで、Active Directoryを使う理由について見てきた。社内システムにActive Directoryが導入されているから使うのではなく、「なぜActive Directoryを使わなければならないのか」を理解できれば、日々の運用管理業務もポジティブに行えるようになるのではないだろうか。
https://atmarkit.itmedia.co.jp/ait/articles/1404/11/news028.html より
まとめの文章を書くときに私がよく使う書き出しは「ここまで〇〇についてみてきた」という文章です。こうやって書くと「あ、終わりが近づいているな」ということを想起できると思うので多用してますｗ よかったら活用してみてください。
5. ほかの人が書いている記事から設計図のパターンを知る
ここまでテクニカルドキュメントでは文章の設計図をキチンと書くこと、シンプルな文章を心掛けることを書いてきました。（←あ、終わりに近づいてる！）今回、シンプルな文章についてはいくつかのポイントについて紹介しました。一方、設計図の部分についてはひとつのパターンしか紹介していませんが、もっと色々なパターンに触れていただいたほうがご自身がドキュメントを書く時の参考になると思うので、ぜひ色々なドキュメントを読んでみてください。その時にそのドキュメントのマインドマップ（冒頭に設計図をマインドマップで表しましたよね）を書いてみてください。そしたらどんなドキュメントの書き方のパターンがあるのか、わかるようになると思いますし、ご自身の執筆技術の幅が広がると思います。
わかりやすい文章と正確な文章
マイクロソフトのテクノロジーに触れている方であれば一度はdocs.microsoft.comというサイトにアクセスしたことがあると思います。そして、とても読みにくい文章と思われたでしょう。
なぜdocsが読みづらいのでしょうか？
よく言われていることは機械翻訳だからってことなのですが、私はもうひとつ理由があると考えていて、それは正確な文章でなければならないからです。docsはマイクロソフトの公式なドキュメントです。間違ってもそこにウソを書いてはいけません。だから厳密さを求めてわかりにくい文章になるのです。公式なドキュメントを読めば、それ以外のドキュメントなんて要らないはずなのになぜ@ITのようなサイトが存在するかといえば、それはわかりやすさを皆が求めているからです。
わかりやすい文章は公式なドキュメントを読むための準備運動、そう思って今日も私はわかりやすさを追求しています。
この記事が気に入ったらサポートをしてみませんか？