読みやすいブログの書き方

#ブログ

渡辺修司

2017.02.03

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

渡辺です。

以前、JUnit実践入門を執筆した経験もあり、社内でもブログの文章が読みやすいと評価を受けています（内容はともかくｗ）。折角なので、技術ブログを書くときに注意する点をまとめてみました。

はじめに結論を書く

一番大切なこと、それは結論を最初に書くことです。

エンジニアには時間ありません。はじめに、何が言いたいか、何を解決するのか、そこを最初に書かないと、読んでて苦痛です。回りくどかったり、話がブレブレだと最悪です。「XXの時、解決するにはXXする」とか「XXについて一言でまとめるとXXです」など、最初にまとめを書きましょう。

見出しですべてを伝える意識を持つ

見出しは大切です。見出しを追っていけば、内容が頭に入ってくるのがベストです。「見出しをまとめてしまったら、本文に書くことなくなった(´・ω・`)」となれば完璧です。

まさに今、蛇足しか書いてません（笑）。

短い文章を繋げる

読みにくい文章は接続詞を多用した、長い文章になりがちです。

AWSは大きなシェアを持ったクラウドサービスで、EC2など仮想サーバなど基本的なサービスだけで無く、RDSといったフルマネージドなサービスや、IoT, モバイルといった特定用途のサービスまで、数多くのサービスを提供しており、それらは基本的に従量課金で使っただけ支払う仕組みとなっています。

これは、一番よくないパターンです。文章が長々と続くと当然のように読みにくくなります。さらに、自分でも何を言っているのか解らなくなり、理論が飛躍することもしばしばです。

AWSは大きなシェアを持ったクラウドサービスです。EC2など仮想サーバなど基本的なサービスだけで無く、数多くのサービスを提供しています。例えば、RDSといったフルマネージドなサービス、IoT, モバイルといった特定用途のサービスです。そして、それらは基本的に従量課金で使っただけ支払う仕組みとなっています。

使っている文章はほぼ一緒です。読んでみると、まったく読みやすさがかわってきます。

文章は短くしてください。

逆接の接続詞を多用しない

エンジニアの文章でありがちなのは「しかし」の乱用です(´・ω・`) 「しかし」が続くと読みにくく、重要なポイントがぶれるため、ピンポイントで使いましょう。

例えば、こんな文章が良くない例です。

CodeDeployのフックでは、デプロイ時にスクリプトを実行できます。しかし、フックスクリプトに実行権限がないと実行できません。しかし、ファイルの実行権をつけてもデプロイ時には反映されません。 permissionsセクションで実行権を設定します。しかし、全部のファイルに実行権をつけるのではなく、実行権を付けるファイルを限定しましょう。

ここまで酷いのはあまり見かけませんが、似たような文章はたまに見ますね・・・。

CodeDeployのフックでは、デプロイ時にスクリプトを実行できます。しかし、フックスクリプトに実行権限がないと実行できません。なお、ファイルの実行権をつけてもデプロイ時には反映されません。 permissionsセクションで実行権を設定します。全部のファイルに実行権をつけるのではなく、実行権を付けるファイルを限定しましょう。

「しかし」は無くても言い場合、他の接続詞に替えてもニュアンスが通じます。 「しかし」をピンポイントで使うことで、言いたいことがハッキリ伝わります。