学校内の技術文書をどう書くか

背景

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

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

目的

  • 様々な傾向の読者に対して,できるかぎりトラブルなく進めてもらうことのできる技術文書・手順書を作る。
  • のちに違う人が担当したとき,応用可能な技術文書・手順書を作る。

前提

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

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

内容

知りたいことに対して最低限どの部分を読めばよいのかを明確化します。実際,次のように見出しを立てています。

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

詳細

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

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

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

参考


  1. 2022年度現在。 ↩︎

  2. 諏訪敬之,ドキュメントに固執せよ。gfnweb,参照 2022-08-12。 ↩︎