この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
資料作成時の文書構成はテンプレートが無い限り迷うものです。とりあえず外部リンクだけを載せたりと、果たして有用な資料なのかと思いながら保存することもありますが、結果として文書検索の結果を濁すだけになりがちです。
書き方の思想とかアレコレ考えずに、とりあえず最初はこれだけ書いていれば更新し続けることで何時の日か有用な資料に化けるかもしれない、というものを考えてみました。
必要なのは2つ
とりあえず、資料の概要とよくありそうな質問について書いておきましょう。
概要
資料の簡単な説明を以下3つの要素で書き出します。
- 何をするのか？
- それに至った背景は？
- 何をもって完了とするのか？
「完了とする」という点でいわゆるIssueと見做せそうですが、何らかの課題解決ではなく一定人数以上への認知を広げることや、一定以上の理解をして貰うことが目的というケースもあるでしょう。
よくありそうな質問
なぜ「よくある質問」ではないのか。それは書いている時点では質問が発生しようがないから。それでは書きようがないと思いますが、ここは少し考え方を変えて検索対策用途としてみます。
概要での説明記述は問と答の組み合わせではないため、フレーズを含む文章の検索には向いているものの疑問への答えとしては成立し難くなります。そこで、概要の内容をFAQ形式に変えて書き出してみます。
このブログについての概要を書き出すとしたら、一例として以下の内容になるかもしれません。
DevelopersIOはクラスメソッドが運営する、「やってみた系」ブログメディアです。
これをFAQ形式にしていくと以下のような内容になるでしょう。
| 質問 | 答え |
|---|---|
| DevelopersIOとは？ | 「やってみた系」ブログメディアです |
| DevelopersIOの運営元は？ | クラスメソッドです |
「資料の水増しじゃないか」と言われそうですが、概要が文章として読み取り難い場合には助かる存在です。推敲手段としてFAQとして書き出した後に概要を手直しという方法もとれます。
概要とよくありそうな質問以外の要素
何かのアプリケーションに関して書いているものであればダウンロードリンクも含めておきます。資料作成の動機に至った関連資料もあれば参考資料としておきましょう。
あとがき
説明用の文面を考えた時にさて何を書くべきかと迷いましたが、文書に辿り着く手段は大体検索であり、且つ検索結果にでる一部引用を見た時に「この資料なら使えそう」と思えるものは、経験上疑問に答えているエリアが存在する文書であるという結論に至りました。
普段FAQが存在する文書は中々見る機会がないでしょう。何が質問になるか分からないのに、敢えてコストを掛けるのはマイナスと見做されやすいからです。では、必ず存在する概要文が果たして正確に汲み取られているのかどうか。そこを補完する形であれば、書き方を変えるだけなので悩みも少ないと思います。
書き出しに悩んだ時のあくまで個人的なやり方です。ただ、全く手が進まない時にはもしかすると参考になるかもしれません。