技術文書に関するガイド

技術文書を書く、または書く技術を向上するためのガイド

Individual ContributorであれEngineering Managerであれシニアになるほどwritingスキルが重要になるという指摘

具体的なスキルの伸ばし方

とにかく読まれるものを書く

ohbarye.icon 文書に対する良いフィードバックを得るための質問集が良い

ツール

ライティングスキルの基礎の基礎には飽き飽きしている人が次のステップに進むための本

「構成を考えてから書き始めましょう」とか「段落を分けましょう」、「書いた文章は読み返しましょう」あたりはマスターしている前提

一文一文を"読み手にわかりやすい"、より洗練された文章にすることを目的としている

読み返して感じる違和感をどうやって払拭するか、その技術がきちんと書かれている

具体的には、テン（、）の打ち方や語順の入れ替え

これらで文章が驚くほどわかりやすくなることを、文の構造を図示し、悪文・訂正文を並べることで示している

ohbarye.icon 小説や詩といったあえてわかりにくい表現を用いる文章表現は目的外としているのも明確で良い

Must・Want・Don'tで技術を伝えていること。

（例）「この場合には必ずテンを打たねばならない(Must)or打ってはいけない(Don't)」

「テンを打つかは筆者に任されるが、思想を明確にしたいなら打った方が良い(Want)」etc.

本書に記されているのはあくまで技術であり、小うるさい規則ではないから、ルールにがんじがらめになり文章表現の幅が狭まるといったおそれはない

むしろ「思想の最小単位としてのテン」や「符号（。、・（「『”？！＝－……｀ etc.）」の考え方・使い方をMust・Want・Don'tの切り分けとともに知ることで、言いたいことや書くべきことをよりわかりやすく表現する術が身に付く

作文の基礎が中心

事実と感想を分ける

「〜だ」を使う、「〜と思われる」を使わない

初めに主張を書き（Tl;Dr）、説明や根拠はあとに書く

ohbarye.icon 当たり前のことを言っているように思えたらある程度身についている可能性あり

文書よりかは記事にフォーカスしているが骨子は共通している

具体的な構成例があってとても良い

発明特許の申請に用いる、特許明細書とほぼ同じフォーマット

とのこと

以下の2点に重心を置く

記事で伝えたいこと

解決したい課題

課題がなく、紹介だけになっている文書は「なんの役に立つのか」理解しづらい