Clean Documentを目指して

Yuichi Sakuraba @skrb

技術文章であってもストーリーが大事。読む人がストーリーに共感できれば、それだけ理解度はぐんと上がるはず。

Yuichi Sakuraba @skrb

たとえば、アウトラインプロセッサのようなツールを使ってストーリーを作り込んでから、細部を書くようにする。マインドマップとかでもいいかもしれません。

Yuichi Sakuraba @skrb

一番重要なのはつかみ。 一番はじめの部分で、この文章がおもしろいかどうかを読者は決める。ここで興味を持ってもらえば、興味が持続する。

Yuichi Sakuraba @skrb

だからといって、つかみで冗談を書けばいいというものではないです。

Yuichi Sakuraba @skrb

たとえば、Aについての技術であれば、Aを導入することで何がうれしいのか、今までは何が問題だったのか、Aはどのように過去の問題を解決するのかなどの背景情報を十分に書く必要がある。

Yuichi Sakuraba @skrb

背景となる部分で読者に「そうなんだよ」と思ってもらえば、半分以上は目的は達している。

Yuichi Sakuraba @skrb

つかみで興味を持ってもらうためには、一見必要ではないようなことも盛り込むことも検討する。たとえば、Aという技術を作った開発者の人となりとか、Aを作るにいたった歴史とか。

Yuichi Sakuraba @skrb

説明は抽象から入って、具象にいたるようにする。抽象だけとか、具象だけということはありえない。必ず抽象的な総論から入って、具体的な各論となるように説明する。

Yuichi Sakuraba @skrb

ただし、抽象と具象のバランスはターゲットとしている読者によって変化する。開発写であれば具象が多くなるが、マネージャだったら抽象を多くするなど

Yuichi Sakuraba @skrb

比喩はとても大事。でも、説明を比喩で終らせてはいけない。AはBのようかもしれないが、A=Bということはありえない。比喩で説明した後は、その違いを含めて、ちゃんと対象について説明する必要がある

Yuichi Sakuraba @skrb

語尾を柔らかくする言葉は使わない。「思います」とか。ホントに思っているのであればいいが、「説明したいと思います」などの使い方は軟らかい表現にしているだけで、それ以外のイミはなにもない。「説明します」で十分。

Yuichi Sakuraba @skrb

接続詞はよく考えて使う。特に「が」 逆接の意味で使っているのかどうかをよく考えて使う。

Yuichi Sakuraba @skrb

日本語は主語を書かないことが多い。しかし、常に主語は何かを意識した文章を書くようにする。主語がはっきりしないと、主張があいまいになる。

Yuichi Sakuraba @skrb

能動態で書ける文章は受動態で書かない。受動態は文章をあいまいにする。

Yuichi Sakuraba @skrb

今はこんなところかな。思いついたら、またツイートします。