学校内における技術文書の書きかた¹

概要

校内（職場内）のいろいろな読み手に対して，できるかぎりトラブルなく進めてもらうことのできる技術文書・手順書の書きかたを考えます。また，いずれ担当を譲ったのち，そのひとが応用できる技術文書・手順書の書きかたを考えます。

背景

私は学校内で情報処理・情報管理関係の業務を担っています²。そのため，教員または生徒に対する技術文書・手順書を書くことがあります。これらの文書をどう書くべきかということにはいつも悩まされます。受け手の知識や態度に幅があり，多くのひとに満足してもらいながらこちらの目的を達することがたいへん難しいのです。偏見が含まれるかもしれませんが，たとえば次のような態度はよく見られます。

• 難しいことはわからないので，とにかく何をすればよいのかだけ教えてほしい。
  • 実際は「丁寧に説明されようが，とにかく代わりにやってほしい」のかもしれませんが，それは別の問題ですから措いておきます。
  • このとき，難しいことが書かれていると「分からない」となり読んでもらえなくなります。
• 面倒なので，どうしてもせねばならないのでなければしたくない。
  • この場合，手順を省いたり変えたりされることもままあります。そのせいでうまくいかないわけですが，本人から自分がマニュアルと違うことをしたという説明はなかなか受けられません。
• 斜め読みし，指示していないことを行う。
  • 資料が分かりにくかった可能性もあります。しかし，対話しながら説明すると往々にして「確かに」といった反応が返ってきます。
• 想定外のことが起きたとき，報告せずに単に中断して放置する。
  • しばらくの間こちらには問題が現れず，うまくいっているかのように見えます。しかし，突然に差し迫った状態で明らかになるのでたいへん困ります。
  • あるいは，本人が不便さを飲み込んでしまうこともあります。
• 納得しなければしたくないので，何をさせられているのかが知りたい。
  • 私にはこの向きがあります。いわゆる「おまじない」では応用もできませんし，させられたことによる副作用も知っておかねば不安です。何をさせられているのかが分からなければ，やりたくないわけです。信用していないと言い換えてもよいでしょう。

前提

次のいずれかであれば今回の説明に合うでしょう。

• 作る文書が，あなたが他者に作業を依頼する文書である。
• 作る文書が，あなたが他者に仕様を説明する文書である。
• 作る文書が，あなたが他者に規則を説明する文書である。

内容

知りたいことに対して少なくともどの部分を読めばよいのかを明らかにします。実際，次のように見出しを立てています。文書の中身によって，見出しの一部を省くことがあります³。とくに，単純なときには「背景」「詳細」「参考」は欠けがちです。しかし，ここに挙げていない見出しを同じ水準で置くことはあまりありません。さらに下位の見出しをそれぞれの中で作ることはあります。

1. 概要⁴
   • 何をしてもらい，それによってどうなるのかを伝えます。この部分により，「あなたも作業をしてください」と求めます。書かれていることが達せられなければならない理由は背景で述べられますが，とくに重要なのであればここでも軽く触れてよいでしょう。それにより，「よくわからないから放置する」例を減らすことができます。
   • たとえば，「某ソフトウェア を Ver1.1 に更新する」では「更新しなくてもいいや」と思われかねません。「新年度以降の成績計算に欠かせないため，某ソフトウェアを Ver1.1 に更新せねばならず，その方法を紹介する⁵」などとすればよいでしょう。
   • 規則の場合も，それを作った理由を載せます。あなたも，無意味な規則など守りたくないでしょう。
2. 背景
   • この文書・作業・規則がなぜ必要になったのか，経緯を伝えます。これにより，「どうしてこのような手間をかけなければならないのか」という疑問に答えます。
   • 引き継いだひとは，この文書が作られたときの状況を察することができるでしょう。
3. 前提
   • この文書の内容を進めるための要件を伝えます。これがないと，思わぬ質問を生むことになります。たとえば，「学校貸与の端末を使って家から学校のフォームに接続する」説明をしたいときには「学校貸与の端末でなければならない」ことを強調しておかねばなりません。さもなければ，「私物の端末で作業したがうまくいかない」といった問い合わせがたくさん寄せられるでしょう。
   • 前提は，本文のなかに自然と埋め込まれていると読み飛ばされがちです。見出しを別に立てる価値があります。
   • 前提に合っていないとき，どうすべきかも載せておくべきでしょう。何もしなくてよいのならはっきりとそう書き，問い合わせるべきなら誰に問い合わせるのかを伝えましょう。
4. 内容
   • ここでは，実際に行うべきこと・外から見て何が起きるかを伝えることに集中します。ほぼ何も分かっていないひとでも進められるように書くことが要です。できれば，スクリーンショットを丸で囲んだりしながら示すとよいでしょう。
   • 番号付きの箇条書きにし，作業を明らかにしましょう。脇に逸れたり，余計な解説をしてはいけません。
   • トラブルが起きたときの問い合わせ先を載せておきましょう。
5. 詳細
   • 「内容」で指示したことの根拠や工夫を伝えます。あるいは，内部でどのようなことが行われているかを説明します。副作用があるのなら，それも書きます。
   • この部分で，「おまじない」に理由がつきます。詳しいひとであれば，自分にとってよりよい方法を見つける手助けになるかもしれません。
   • 引き継いだひとにとっては，この部分こそがありがたいものとなるでしょう。
   • こうした部分は，内部のための引き継ぎ文書として切り離されてしまうことが多いのかもしれません。しかし，理由が見えていることは多くの人にとってよいことです。不満を持っているひとが納得してくれるかもしれません。また，内容に興味を持ってもらえる可能性もあります。
6. 参考
   • 参考文献を載せます。資料を作るために参考にしたものはもちろん示さねばなりません。ほかに，発展的な意味で見てもらうとよいものを載せてもよいでしょう。

詳細

想定読者がどう動くのかを考えてみましょう。

• 難しいことはわからないので，とにかく何をすればよいのかだけ教えてほしい。
  • 「前提」を確かめ，「内容」を守ってもらえばよいことになります。「背景」「詳細」「参考」は見出しから読み飛ばしてもらえるだろうと考えています。
• 面倒なので，どうしてもせねばならないのでなければしたくない。
  • 「概要」「背景」によって納得してもらえるでしょう。
• 斜め読みし，指示していないことを行う。
  • 「内容」の書きかたが要です。番号付きの箇条書きにしていることで，迷わず作業してもらえるようにしています。
• 想定外の事態が発生したとき，報告せずに単に中断して放置する。
  • 「概要」で，行わなければ困ることが伝わっていれば，問い合わせてもらえることが増えるでしょう（この類については，困っても放置されることが多少は起きるかもしれませんが，減りはするはずです）。
• 納得しなければしたくないので，何をさせられているのかが知りたい。
  • 「背景」「詳細」によって納得してもらえるでしょう。

このウェブサイトでの「技術記録」は，一部を除きこの体裁を守っています。もちろん，ほかにふさわしい型が明らかなときは無視しています。たとえば，パッケージの紹介はこの型に則っていません。また，「背景」と「目的」は併せて「背景と目的」とすることもあります。「詳細」「参考」はとくになければ省略します⁶。

参考

• ドキュメントに固執せよ⁷
  • これはより狭義のドキュメントに関するものですが，あらゆる文書作成で参考になります。