00:05
こんにちは、ながおかのプログラミングチャンネルです。
今日は、ドキュメントの書き方で自分がちょっと気を付けていることを話したいと思います。
ドキュメントって言っても、いろいろあると思うんですが、
自分がよく書くのは、ソフトウェアの使い方だったり、他の人に説明するようなドキュメントですし、
こないだ書いた本も、ドキュメントで言えばドキュメント文章ですね。
あとブログポストだったり、もっと言えばツイッターとか、そういうのも、
例えばフェイスブックのSNSなどの投稿も、ドキュメントで言えばドキュメントで文章を書くということだと思います。
自分がいろんな文章を書くときに気を付けていることは、
読み手がいかにストレスなく読めるか、みたいなところを一番気を付けています。
というと、例えば自分が他のドキュメントを読むときに、
これなんかわかりにくいなぁだったり、あとこれすごい、ここのこれどういう意味なんだろうって、
書く側からすると一瞬でわかるようなことでも、読む側からするとすごい色々調べたりして、
ああだこうだして、やらないと出てこないようなことって結構あると思っていて、
そういう例えば非対称性のようなところで、
書き手がちゃんと気を付けてあげれば一瞬で解決できることのようなことを気を付けるようにしています。
この自分が書くドキュメントってほとんどストーリーだったり、
人の感情に訴えかけるというものよりは、どちらかというと実理的な、
わかることがわかればいいというようなものが多いので、そのような考え方になっていますが、
もっとストーリーだったり小説のような文章だとまたちょっと違ってくるのかなというふうに思います。
その読み手のストレスがないというのを一番というのは、
例えば最初にTLDRとかよく言ったりしますが、
Too Long Didn't Read という略で、そのサマリが最初にあったりとか、
あと、記事などへのリンクはなるべく貼るようにする。
別にGoogleればわかるじゃんっていうのはあるんですけど、
そのGoogleった後でどの記事が適切なのか、どの説明が適切なのかというのを選択するのも結構ストレスだし、
そもそも間違ったものに行ってしまうということもあると思うので、
自分が意図する記事が明確にある場合はそのリンクを貼るであったり、
あと略語は基本的に使わないようにします。
する、使う場合は必ず最初で1回使ってその後説明するであったり、
あとは、そうですね、何だろうな。
あとは自分が読んでいて、これなんかわかりにくいなと思ったところを日々メモしたりして、
そういうのをしないようにしたりはしています。
03:02
基本的に相手の知識がない前提、別にそれはバカにするとかそういうことではなくて、
どんな人にでも、もちろん限界ありますが、どんな人にでもわかるようにと願って書いています。
そういった感じで書くと、なるべくいろんな人がすぐわかるような文章にできるんじゃないかなと思います。
自分、皆さんもこういったことを気をつけているとかあったらぜひいろいろ教えてください。
あといいねやフォローもぜひお願いします。
というわけでありがとうございました。
