技術文書アンチパターン集

doc-anti-pattern.md

• 怖い人を恐れすぎる
  • 彼らはターゲットじゃない
  • わざわざ難しい専門用語を使おうとして自滅する
  • こんな基本的なこと説明しなくて良いのではと思って肝心な部分を省略してしまう
• 分かっていないのに説明しようとする
  • 調べて書くか書かないかどっちかにしろ
• 知らないことがあってはいけないと思い込む
  • そんな万能人間はいない
  • 調査に時間がかかりすぎる
  • 知らないことを素直に認めろ
• 全てを網羅しようとする
  • 詳しけりゃいいと思って寄り道しすぎる
• 回りくどい
  • 何でもかんでも背景から説明しようとする
  • 何が言いたいんだ結論を言え
• 最初に公式を書く
  • 具体例がないのに一般化されたものを最初に見せられても分からない
• 現実的な例でないといけないと思い込む
  • 足し算の説明にストーリーは要らない
  • そのコードを書くメリットを追求しすぎて例が複雑になる
  • 別にライブラリにある関数を再実装してもいい
• 一文ずつ逐一説明する
  • コードと同じことを自然言語で説明し直す
  • 見りゃわかる
• お手本を見て不安になる
  • 他人がそう書いていてももっと説明を書き足さないといけない訳ではない
• ストイックすぎる
  • 「〜しなければなりません」いつでも仕事のような真面目さ
• 一文に新情報を２つ出す
  • 「〜なので（新情報）、〜です（新情報）」分けろ
• ハイコンテクストなネタ
  • 「よくこんなことありますよねw」お前の中ではな
• 押し付けがましい
  • 「〜でしょう」んなこたない
• 簡潔すぎる
  • 「〜は〜の〜です」今なんて？
  • 具体例を挙げろ
• 一度の説明で理解できる前提
  • それさっき必要十分な説明したよね
  • 別の角度から何周しても良い
• つなぎの文章が多すぎ
  • 「それでは〜してみましょう」いいから早よ先行け
• 説教臭い
  • 私が踏んだ罠をどうか皆様においても踏まれませぬよう
  • より良いプログラムを書くための秘訣は〜です
  • 偉そう、もっと謙虚になれ
• 本は堅く書くものだと思い込む
  • 語りかけるように書いていいし、そのほうがわかりやすい
• 説明の順番にこだわりすぎる
  • おまじないがあってもちゃんと断っておけば多少順序が入れ替わっても大丈夫
• 感情的になる
  • 苦労させられたライブラリにはつい嫌味の一言も付け加えたくなる
• 英語は読めて当然という態度
  • 詳しくはこのリンクの先に書いてあるよ
  • 自分だって読むの苦しいくせに
• 経験していないことを語りたがる
  • 大規模開発では〜
  • CTO としては〜
  • 知らんだろ