ドキュメントにおける "What is this?" "これは何？" 項目は無ければ無いほどいい、という話

What is this?

タイトルの通りです。下記で掘り下げます。

理由

タイトルはドキュメントの「顔」です。

本来 "What is this?" を表すのがタイトルであり、タイトルでどれだけ簡潔・明確に示せるかがドキュメント作成のカギです。

タイトル と "What is this?" は天秤関係になりますが、もちろんタイトルのほうが優先度高いです。

つまり「タイトルは適当に書いて "What is this" で何とかしよう」は甘え、ということです。

どうしても付けたくなったとき

そもそも "What is this?" は閲覧者にとって価値のある情報ではないことが多いです。

自分で読んでみて、価値があると感じる場合は、

• タイトルがそもそも曖昧適当過ぎる
• "What is this?" なのに What 以外に踏み込んでいる
• 結論が含まれている

といったケース。

まずタイトルで吸収できないか考えましょう。もしくは、タイトルですでに吸収できてるケースが多いです。

次に、 5W1H における What 以外が含まれてないか考えましょう。

When -> 背景・バージョン情報 など
Why -> 前提・理由・原因 など
Where -> 環境情報・ネットワーク情報 など
Who -> 筆者の情報 や 関係者・関係要素 など
How -> 具体的な内容や結論

これらが含まれている場合は、分解していきましょう。

おそらく "What is this?" は無くなります。

許されるケース

タイトルに強い文字制限があり、どうしても表せない
=> 仕方ないです。まず重要ワードを箇条書きで抜き出して優先度付けをして、盛り込み方を工夫しましょう。そのうえで "What is this?" が必要か判断しましょう。

煽り記事
=> 例えば「お前らの useReducer の使い方は間違ってる」のようなやつ。まず閲覧者を興奮させ、記事に遷移させたあと言い訳をして一気に沈下させる。 "What is this?" には言い訳の責務を持たせられます。

あとがき

自分は あるアプリケーションのサポートデスクをしていた経験があり、テキストだけでどれだけ明瞭かつ簡潔に

• 情報提供依頼
• 操作依頼
• 調査状況
• 調査内容
• 直接原因
• 根本原因
• 回避策
• 仕様
• 今後の対応

を伝えられるかというのを 死ぬ気で死ぬほどやってました。

JavaScript を Javascript と書くだけで怒られるような世界です。

なお、この記事自体も煽り記事ですが、世の中の "What is this?" 文化にもの申したかっただけです。

ちなみに「という話」を付けるのも甘えだと思っています（甘えました）