学校内における教員・生徒向け技術文書の書きかた
目次
学校内における教員・生徒へ向けた（一般には、職場内の幅広い層へ向けた）の技術文書・手順書を作るにあたっては、受け手の知識や態度の幅が大きいことを気にかけねばならない。 さまざまな読み手がいる中で、問題なく手順を進めてもらうことと、気持ちの面で満足してもらうことを折り合わせて書くにはどうすればよいかを考える。 さらに、その技術文書・手順書にかかる業務を引き継ぐにあたっても、このときに作った文書で足りるよう工夫したい。
ここでは、次のいずれかの文章を書くことを考える。
- 作る文書の目的が、あなたが他者に作業を依頼することである。
- 作る文書の目的が、あなたが他者に仕様を説明することである。
- 作る文書の目的が、あなたが他者に規則を説明することである。
背景
私は2022年度現在で、数年にわたって校内の情報処理・情報管理関係の業務を任されている。 そのため、教員または生徒に対する技術文書や手順書を作ることが多い。 これらの文書をどう仕上げるかについては、いつも悩まされる。 教員・生徒を問わず受け手の知識や態度の幅がきわめて大きいため、多くのひとに満足してもらいながらこちらの目的を達することがたいへん難しい。 偏見もあるやもしれないが、たとえば次のような態度はよく見られる。
- 難しいことはわからないので、とにかく何をすればよいのかだけ教えてほしい。
- 実は「どれほど丁寧に説明されようが、とにかく代わりにやってほしい」のかもしれない。しかし、それは別の問題であるからここでは避ける。
- このとき、難しいことが書かれていると「分からない」となり読んでもらえない。
- 面倒なので、どうしてもせねばならないのでなければしたくない。
- このとき、手順を省いたり変えたりされることもままある。そのせいでうまくいかないわけだが、本人から「私はマニュアルとは異なることをした」と伝えられることはまずない。
- 斜め読みし、書かれていないことを行う。
- 技術文書・手順書が分かりにくかったのかもしれない。しかし、その場に行ってやりとりをしながら説明すると往々にして「確かに」といった反応が返ってくる。
- 本人の想定や能力を超えることが起きたとき、こちらへ伝えることなく単に諦め放置する。
- しばらくの間こちらの目には問題が現れず、うまくいっているかのように見えることが難しい。しかし、差し迫った状態で明らかになり、たいへん困るのがこの例である。
- 手間をかければどうにかなるのであれば、本人が扱いにくさを飲み込み、ついに黙ったままのこともある。
- 納得できなければしたくないので、何をさせられているのかが知りたい。
- いわゆる「おまじない」では応用も効かず、させられたことによる副作用も考えねば不安が残る。何をさせられているのかがわからなければやりたくないのである。自らが理解するまで信じられないと言ってもよい。
- 私はこの類である。
解決
知りたいことがひとによって違うことはどうにもできない。 そこで、それぞれが読むべき箇所を明らかにする。 具体的には、次のように見出しを立てる。
- 概要
- 背景
- 解決
- 補足
- 参考
文書の中身によって、見出しの一部を省いてもよい。ただし、これらの見出しと同じ水準で、新たな見出しを置くことはしない。一方で、下位の見出しをその場限りで作ることはある。
ウェブサイトでは、ここから２か所を変える。
- 「概要」は書かずに本文のはじめにそのまま載せる。これは、一覧ページに本文の頭がそのまま使われるからである。
- 改訂履歴があれば、「参考」の後ろに「改訂」を立てる。ふつうの文書であれば、発行日が書かれるはずであるから「改訂」は要らない。かえって読み手を惑わせるだろう。ただし、引き継ぎのために書き残し、印刷にあたって取り除くことは悪くない。もしも pandoc を用いて書くのであれば、「改訂」はコメントアウトしておくとよいだろう。
概要
- ここから先の内容にかかわらず、概要をあまり長くしてはならない。長くなりそうであれば、背景か解決に振り分ける。
- なぜせねばならないのか、何をしてもらいたいのか、それによりどうなるのかを伝える。この部分で「あなたも作業をしてください」と求める。書かれていることが達せられなければならない理由は背景で述べればよいが、大切なのであればここでも軽く触れる。このことにより、「よくわからないから放っておく」例を減らすことができる。
- たとえば「某ソフトウェアを Ver. 1.1 に更新する」では「そのままでもいいや」と思われかねない。「新年度からは成績計算のルールが変わる。新しいルールで計算するためには、某ソフトウェアを Ver. 1.1 に更新せねばならない。ここでは、その方法を紹介する」などとすればよいだろう。
- 規則を示すときも、なぜそれを作らねばならなかったかを伝える。あなたも、正当な理由なく増えた規則など守りたくないだろう。
- この文書に書かれた手順を進めるための要件があれば、それを載せておく。これをしなければ、思わぬ質問を生むことになるだろう。たとえば、「学校貸与の端末を使って家から学校のフォームに接続する」という文書を書くとしよう。それならば、はじめに「学校貸与の端末でなければならない」ことを強調しておくべきである。そうでなければ、「私物の端末で作業したがうまくいかない」といった問い合わせが寄せられることとなる。問い合わせがなくとも、途中まで文章を読まされた後に自分は対象外だったと知る読者を生むことになってしまう。読み飛ばされてしまうことのないよう、はじめに目立つように書いておくべきであろう。
- 要件に合わないときにどうすべきかも載せておくほうがよい。何もしなくてよいのであればはっきりとそう書き、問い合わせるべきであれば誰に問い合わせるのかを伝えたい。勝手に判断され、後に問題となることを少しでも避けよう。
背景
- この文書・作業がなぜ必要になったのか、その経緯を伝える。これにより、「どうしてこのような手間をかけなければならないのか」という疑問に答える。
- 業務の引き継ぎにあたっては、この文書が作られたときの状況を察することができる。ほとんどの業務は、通知によって増やされたか、現場の事情によって止むを得ず増やしたかのいずれかである。増えた理由がわかっていれば、その状況さえなくなれば根拠をもって取りやめることができる。しかし、引き継ぎを繰り返すうちになぜ始まった業務かを見失えば、続けるほかない。背景を伝えることはきわめて大切である。
解決
- ここでは、実際に行うべきこと・外から見て何が起こるかを伝えることに集中する。想定読者に入っていれば、よくわかっていないひとでも進められるように書くことが鍵となる。手順書であれば、スクリーンショットを取り、丸で囲むなどするとよいだろう。
- 作業手順を載せるときには、番号付きの箇条書きにするとよい。脇に逸れたり、詳しい説明を加えてはならない。
- 困ったときの問い合わせ先も併せて載せておく。
補足
- 「解決」に載せた内容についての根拠や工夫、あるいは内部で何が行われているかを伝える。副作用があれば、ここで述べる。「解決」では簡単のために隠していたことをすべて明らかにしよう。
- ここで「おまじない」に理由がつく。また、詳しいひとにとっては、よりよい手続きを見つける助けになることもあろう。
- 業務を引き継いだひとにとっては、この部分こそがありがたいだろう。このような内容は、技術文書・手順書からは切り離され、引き継ぎ文書として残されることもあるかもしれない。しかし、それではいつか引き継ぎ文書は忘れられてしまうだろう。また、多くのひとにとって、理由が見えているのはよいことである。不満を持つひとが納得するきっかけになるかもしれない。また、興味を持ってもらえるかもしれない。内容がまったくわからないひとであっても、説明しようとする意思を汲んでくれるかもしれない。
参考
- 参考文献を載せる。
- 資料を作るために参考にしたものは、文献としてもちろん示す。
- 興味のあるひとに向けて、発展的な記事を載せてもよいだろう。
補足
想定読者の動きを考えてみよう。
- 難しいことはわからないので、とにかく何をすればよいのかだけ教えてほしい。
- 「概要」「解決」を読んでもらえばよい。「背景」「補足」「参考」は、見出しの名から読み飛ばされることを期待している。
- 面倒なので、どうしてもせねばならないのでなければしたくない。
- 「概要」「背景」「解決」を読んでもらえばよい。「背景」によって、せねばならないことに納得してもらいたい。
- 斜め読みし、書かれていないことを行う。
- 「解決」の書きかたが要となる。番号付きの箇条書きにしていることで、迷わず作業してもらえるものと信じたい。
- 本人の想定や能力を超えることが起きたとき、こちらへ伝えることなく単に諦め放置する。
- 「概要」で行わなければ困ることが伝わっていれば、問い合わせてもらえることが増えるだろう。
- 納得できなければしたくないので、何をさせられているのかが知りたい。
- 「背景」「補足」によって納得してもらいたい。
もちろん、業務において、他者が思った通りに動くことを期待するのは誤りである。そんなことでは、気苦労は尽きないだろう。しかし、こちらの工夫によって、少しでもこちらのなすべき手助けが減れば、ありがたいかぎりであろう。
少なくとも、別に引き継ぎ資料を書く手間だけは省ける。私はこの書きかたを取り入れてしばらく経つが、やってよかったと感じている。このウェブサイトにおいても、「技術」では原則としてこの体裁を採っている。
参考
- https://gfngfn.github.io/ja/posts/2022-06-18-be-a-documentation-geek/
- 諏訪敬之
- ドキュメントに固執せよ
- gfnweb
- 参照 2022-08-12
- より狭義のドキュメントに関する記事だが、あらゆる文書作成で参考にできるだろう。
改訂
- 改訂： 2024-10-16
- タイトルを変更した（「学校内における技術文書の書きかた」から、内容を明らかにするため）。
- 見出し「内容」を「解決」に、「詳細」を「補足」に変え、「前提」を除いた。「前提」はできるだけ早く目にすべきであり、概要に取り込むほうがよいとの結論に至った。
- 全体を加筆・修正した。
- 改訂： 2023-08-12
- タイトルを変更した（「学校内の技術文書をどう書くか」から、内容を明らかにするため）。
- 見出し「目的」を「概要」に変え、「背景」の後ろから前へ動かした。文書の意味が先にあるほうが、読み手にとってストレスがないと考えたためである。
- 「新年度以降の成績計算に欠かせないので、某ソフトウェアを Ver. 1.1 に更新する」から「新年度以降の成績計算に欠かせないので、某ソフトウェアを Ver. 1.1 に更新せねばならず、その方法を紹介する」へ変えた。これは「目的」が「概要」に変わったことによる。
- 見出しの削除や追加について述べる位置を動かした。