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

渡辺です。

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

はじめに結論を書く

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

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

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

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

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

短い文章を繋げる

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

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

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

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

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

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

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

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

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

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

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

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

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

文の流れを意識して言い回しを替える

日本語は柔軟なため、言い回しが多く存在します。

1. AWSは大きなシェアを持つクラウドサービスです。
2. AWSはクラウドサービスで大きなシェアを持っています。

どちらの言い回しを選択するか、そんなことを考えたことありますか？

実は、この文だけでは判断できません。 前後関係から、一番流れの良いパターンを選択します。

1. AWSは大きなシェアを持ったクラウドサービスです。EC2など仮想サーバなど基本的なサービスだけで無く、数多くのサービスを提供しています。
2. AWSはクラウドサービスで大きなシェアを持っています。EC2など仮想サーバなど基本的なサービスだけで無く、数多くのサービスを提供しています。

この２つを比較するのであれば、1の方が流れがいいのです。 これは次の文章が「サービス」について述べているからです。 次の文章が他のクラウドサービスと比較したシェアの話であれば2がしっくり来ます。 文章では流れが重要です。 一度書いた文を、流れに合わせて組み替えてみましょう。

文章は圧縮する

ブログの文章は、考えながら書いていきます。 考えをダダ漏れさせているので、長くクドく読みにくい文章になるのが当然です。 なので、書き殴った後、2-3割を削りましょう。

例えば、最初の文章はこんな感じです。

CodeDeployのフックでは、デプロイ時にスクリプトを実行することができます。しかし、フックスクリプトに適切な実行権限がないと実行に失敗します。

不要そうな部分を削ります。

CodeDeployのフックでは、デプロイ時にスクリプトを実行できます。しかし、フックスクリプトに実行権限がないと実行できません。

圧縮すると、回りくどい感じが取れてきます。 特に語尾が無駄に丁寧になって解りにくいことが多いです。 必要の無い接続詞も除去しましょう。

まとめ

読みやすい文章は、適切な見出しと、流れがよく短い文章で構成されています。 慣れてくればパターン化できますので、ちょっとだけ意識してみてはどうでしょうか？