【書評】技術ブログの書き方を教えてくれる本を読んでみた -Writing for Developers-

はじめに

洋書ですが、"Writing for Developers"という技術ブログの書き方を教えてくれる本を読んでみました。

www.manning.com

以下は公式ページにあった概要の翻訳です（ChatGPTで翻訳）。

「Writing for Developers」は、優れた技術的洞察を素晴らしいブログや記事に変える手助けをします。著者のピョートル・サルナとシンシア・ダンロップは、エンジニアとプロのライターという異なる視点を組み合わせ、説得力のある作品を書くためのサポートを提供します。この本は一般的な執筆ガイドではなく、技術的なトピック、執筆者、読者に特化して焦点を当てています。

楽しい例やユーモラスなイラスト、たくさんのジョークを通して学べます！この本は、アイデアの生成と優先順位付けから、計画、執筆、改訂の際に考慮すべきこと、成功したブログ投稿をさらなる機会への足がかりとして活用する方法まで、執筆プロセス全体をカバーしています。

Writing for Developers

僕も技術ブログをたくさん書いてきた人なので、この本に書いてある内容がどれくらい同意できるのか、そしてどれくらい僕の知らない新しい情報があるのかが気になって読んでみました。

本書の目次

以下は目次の翻訳です（ChatGPTで翻訳）。

第1部：基本原則
1. なぜ書くのか
2. 何を書くべきか
3. 読者を魅了する

第2部：ブログパターンの適用
4. 「バグハント」パターン
5. 「Xで書き直した」パターン
6. 「どうやって作ったか」パターン
7. 「学んだ教訓」パターン
8. 「トレンドに関する考察」パターン
9. 「マーケティングっぽくない製品の視点」パターン
10. 「ベンチマークとテスト結果」パターン

第3部：執筆プロセスの確立
11. 作業用ドラフトの作成
12. ドラフトの最適化
13. フィードバックの取得
14. 完成させる

第4部：プロモーション、適応、拡張
15. 注目を集める
16. ブログ記事からカンファレンストークへ
17. 本を書きたいなら

付録A. 執筆と出版のリソース
付録B. AIの使用と濫用

本書の感想

想定している技術ブログのレベルが高い

まず、本書で扱っている「技術ブログ」は僕が想像していた「技術ブログ」よりも少しレベルの高いものでした。
「レベルが高い」というのは「技術的に高度」という意味です。

たとえば10章の事例として挙げられていたのが "Redpanda vs. Kafka: A performance comparison"（RedpandaとKafkaのパフォーマンス比較）というブログ記事です。
実際にアクセスしてもらうとわかりますが、「エンジニア歴1年目」みたいな人が書けるような内容ではありません。

www.redpanda.com

本書ではブログの内容をそのままスライドに書き起こせばすぐに技術カンファレンスで発表できるような、そういうレベルの技術ブログを想定しています。
実際、16章ではブログの内容をベースにしてカンファレンスで話すにはどうすればいいか、という話が書かれています。

もちろん、「エンジニア歴1年目」みたいな人が参考になるような内容もいくつかはありますが、本書の対象となる読者は「すでにエンジニアとして豊富な経験と実績を持っているが、それらをまだ外部に情報発信したことがない人」になるんじゃないかなと思います。

英語が母国語ではない人向けのアドバイスが載っている

また、本書ではところどころに「英語が母国語ではない人向けのアドバイス」が載っている点も興味深かったです。
これはどうやら筆者の一人であるPiotr Sarna氏がポーランド出身だからみたいです。
なので、「日本人だけど英語で技術ブログを書いてみたい人」や、「海外の技術カンファレンスで発表してみたい人」が読むと参考になりそうです。

生成AIの活用方法が出てくる

他には随所に生成AIの活用方法が出てくる点もイマドキだな〜と思いました。
僕はブログを書くときはほとんど生成AIは使っていませんが、今後はちょっとずつ使ってみようかなと思いました。

本書はまだ未完成。そして実は無料で読める！？

2024年8月時点では本書は実は未完成です。
大半の章は執筆済みですが、最後の「付録A. 執筆と出版のリソース」と「付録B. AIの使用と濫用」はまだ執筆されていません。
「未完成だけど執筆済みの部分なら読めますよ」というManning Early Access Program (MEAP)があるので、これを使って僕は電子版を購入しました。

が！！

さっき気付いたんですが、本書は無料で読めるみたいです。
公式ページのtable of contents（目次）に以下の文章があります。

You can see this entire book for free. Click anywhere in the table of contents to start reading
(この本全体を無料で読むことができます。目次のどこでもクリックして、読み始めてください)

Writing for Developers

本当に？と思って目次のリンクをクリックしてみると・・・読めました！！

ずっと無料なのか、期間限定なのかはわかりませんが、現時点では無料で読めるみたいなので興味がある人は公式ページにアクセスしてみてください。

www.manning.com

2024.8.18追記：完全無料ではないようです

コメント欄にて「無料で読める部分ですが、制限がかかっているようで、数パラグラフまでは読めますが、それ以降はMANNING ONLINE のサブスクリプションを購入しなければ読めませんでした」という情報を教えていただきました。
コメントしてくださった id:kwy さん、どうもありがとうございます！

まとめ

というわけで、このエントリでは僕が読んだ "Writing for Developers" という本を紹介してみました。

本書の対象となっている「技術ブログ」が僕がふだん書くような技術ブログよりも高度なものだったので、すべての内容がすぐに役に立つわけではなかったですが、将来「海外に向けて発信したい」とか「技術的にもっと高度な内容を発信していきたい」と思ったときは本書が心強い味方になってくれそうです。

ブログを書くときだけでなく、技術カンファレンスで発表するときにも参考になりそうな内容が多かったので、自分の成果をこれからどんどん外に向けて発信していきたいと考えている中級者以上のエンジニアはぜひ本書を取ってみてください。

おまけ

洋書なんてとても読めない (><) って思う人も多いかもしれないけど、僕もたぶん6割ぐらいしか理解できてないから大丈夫w

雑に「だいたいなんとなくわかる」というレベルでがーっと読み進めていって、「ここはちょっと気になるな」と思ったところだけをじっくり読む、みたいな感じで読んでます。

— Junichi Ito (伊藤淳一) (@jnchito) 2024年8月12日

学校の英文和訳みたいに「隅から隅まできちんと日本語に翻訳しなきゃ」みたいなマインドで読むといつまで経っても読み終わらないし、そうしないと何かペナルティーがあるわけでもないので、「とりあえず読み進める。多少わからないところがあっても前へ進め！」というマインドで読むのがお勧めです。

— Junichi Ito (伊藤淳一) (@jnchito) 2024年8月12日

【書評】脳に関わる技術書を2冊読んだ #プログラマー脳 #脳に収まるコードの書き方

はじめに

プログラミングと脳の関係が注目されているのでしょうか？
最近「脳」がタイトルに含まれる技術書が2冊発売されました。

1つは「プログラマー脳」。

プログラマー脳 ～優れたプログラマーになるための認知科学に基づくアプローチ

もう1つは「脳に収まるコードの書き方」です。

脳に収まるコードの書き方 ―複雑さを避け持続可能にするための経験則とテクニック

個人的にもプログラミングと脳の関係はちょっと気になるので、2冊とも買って読んでみました。
このエントリではこの2冊の感想を書いてみます。

書評：プログラマー脳

サブタイトルに「優れたプログラマーになるための認知科学に基づくアプローチ」とあるように、プログラマの認知能力に関する研究をベースにコードの理解しやすさ・しにくさを議論する本で、いろいろと興味深く読めました。

サンプルコードはC++やJavaで書かれているケースが多いですが、題材としてちょこっと出てくるだけなので、C++やJavaを知らなくても全然大丈夫です。

プログラミングを始めたばかりの人にはピンと来ないかもしれませんが、現場で2〜3年働いている経験者なら実務で見たコードを思い出しながら、「あー、だからあのコードは読むのがしんどかったのか〜」と納得できるかもしれません。

書評：脳に収まるコードの書き方

うーん、この本は正直ちょっと期待外れでしたね。
悪い本ではないと思うのですが、「プログラマー脳」に比べると「別に脳みそ関係ないやん」っていう話題が多かったです。
僕としては、プログラミングと脳の関係に注目した斬新な切り口でコードの良し悪しを語ってほしかったなあ。

この本を読みながら僕が頭に思い浮かべたタイトルは「達人プログラマー・実践編」です。
別の本の名前を付けちゃってますけど。

要するに、「達人プログラマー」みたいに、良いプログラマになって良いコードを書くための考え方や習慣を、具体的かつ実践的なコード例とともに解説した本、という感じです。
タイトルにある「脳に収まるコード」というのは、脳みそそのものの話ではなく、「理解しやすい良いコード」を意味しているだけなんだと思います。

もちろん内容自体は間違ったことは書いてないですし、現場経験の浅いプログラマは知っておいた方が良い知識がたくさん載っていますが、僕みたいな20年選手が読むと「せやな」「それな」という話題がほとんどでした。

あと、割合的に C# に特化した内容が多い点にも注意が必要です。
僕は前職で C# をやってたので、C# はそこそこ読めますし、「最近の C# はこんなふうになってるのか。へ〜」と思う点も多かったですが、 C# に触れたことのない若手プログラマが読むとピンと来ない部分が多いかもしれません。

個人的には以下の書籍の内容をひとまとめにした本かな、という印象でした。

• 達人プログラマー
• リーダブルコード
• リファクタリング
• レガシーコード改善ガイド

そこに筆者の考える「C# ならこう作るといいよ」という具体的なコード例が加わる感じです。
なので、この本が一番役立つのは「若手 C# プログラマ」なんじゃないかなーと思います。

原題には「脳」が含まれるのか？

ちなみにどちらの本もタイトルに「脳」が含まれていますが、はたして原題はどうなんでしょうか？
ちょっと調べてみました。

「プログラマー脳」の原題は "The Programmer's Brain" です。
こちらは "Brain" が入ってますね。

The Programmer's Brain: What every programmer needs to know about cognition (English Edition)

一方「脳に収まるコードの書き方」の原題は "Code That Fits in Your Head" でした。
"Brain" ではなく "Head" ですね。

Code That Fits in Your Head: Heuristics for Software Engineering (Robert C. Martin Series) (English Edition)

直訳すれば「頭に収まるコード」でしょうか。
たしかに「脳に収まるコード」と書いた方が、日本語として収まりがいいですが、「プログラマー脳 = The Programmer's Brain」に比べるとタイトルからして内容の「脳みそ感」はちょっと薄くなってしまうのはやむを得ないのかもしれません。

まとめ

というわけで、このエントリでは最近僕が読んだ「脳」に関する2冊の技術書を紹介してみました。
まだ読んでない人の参考になれば幸いです！

プログラマー脳 ～優れたプログラマーになるための認知科学に基づくアプローチ

脳に収まるコードの書き方 ―複雑さを避け持続可能にするための経験則とテクニック

「脳に収まるコードの書き方」の感想でチラッと触れたこちらの技術書もどうぞ。
いずれも名著ですね。

達人プログラマー ―熟達に向けたあなたの旅― 第2版

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

リファクタリング 既存のコードを安全に改善する（第2版）

レガシーコード改善ガイド: 保守開発のためのリファクタリング

私がメインの検索エンジンをGoogleからBingに変えた理由

はじめに

タイトルの通りですが、今年に入ってからメインの検索エンジンをGoogleからBingに変えました。

なぜ変えたのか？

それはこのブログを含む個人ブログがGoogleの検索結果に上がりにくくなってきたからです。

Googleで個人ブログが検索結果に上がりにくくなった例

たとえば、先日僕は自分の車のワイパー交換の方法をブログに書きました。

blog.jnito.com

Bingで「volvo xc60 ワイパー交換」というキーワードで検索すると、僕のブログがトップに表示されます。

一方、Googleだと同じキーワードで検索しても全然表示されません。
いくらスクロールしても最後まで僕のブログは表示されませんでした。

「xc60 ワイパー 自分で交換」なら表示される

しかし、インデックスに登録されてないわけではありません。
「xc60 ワイパー 自分で交換」みたいなキーワードにするとGoogleでも2番目に表示されます。
（Bingでもトップに表示されます。）

「xc60 ワイパーゴム」は表示されない

次にキーワードを「xc60 ワイパーゴム」に変えて見ましょう。
すると最初のキーワードと同じようにBingでは僕のブログがトップに表示されました。

一方、Googleではまったく表示されませんでした。

同じような事例をもう一つ

もう一つ同じような例として以下のブログ記事で検証してみます。

blog.jnito.com

このブログ記事はFUJIGEN(FGN)のフルアコ（フルアコースティックギター）にThomastik-Infeldというギター弦を張るためにギターを少し改造した、という内容です。
「FGN + フルアコ + Thomastik-Infeld」という組み合わせはめちゃくちゃニッチで、こんなブログを書いてるのはたぶん日本中で僕しかいません。
てか、そもそもネット上に同じような情報が見つからなかったのでブログを書きました。

「fgn フルアコ Thomastik」という検索キーワードでBingを検索してみます。

ご覧のとおり、僕のブログが最初に表示されました。
そんな情報を書いてる人は僕以外いないはずなので、当然といえば当然でしょう。

ではGoogleだとどうでしょうか？

Googleはなぜか記事本体ではなく、僕のXのポストを最初に表示しています。

2ページ目に行くと今度もやはり記事本体ではなく、はてなブログの記事一覧が表示されます。

結局最後まで僕のブログ記事本体のリンクは表示してくれませんでした。

記事タイトルで検索しても表示されない

ちなみにこの記事の場合、「FUJIGENのフルアコにThomastik-Infeldの弦を張る」という記事タイトルそのものをキーワードにしても表示されません。

siteを限定したら表示される（意味なし）

「FUJIGENのフルアコにThomastik-Infeldの弦を張る site:jnito.com」というようにsiteを限定してようやく表示されました。

もはやこれって、Googleから「お前のブログは絶対表示させないぞ」と言われているに等しいと思います。

個人ブログを隠そうとするGoogle？

このようにキーワードの指定方法によってはGoogleでは表示されるものの、Bingに比べると僕のブログは検索結果に引っかかりにくくなっています。
前述のワイパー交換やギター弦のブログ記事に限らず、最近自分の書いたブログ記事はどれも同じような傾向にあると感じています。

あくまで個人的な感覚ですが、昔のGoogleは今のBingみたいに「このキーワードだったら引っかかるっしょ」というキーワードを指定すれば自分のブログが（1位ではなくても）ほぼ百発百中で引っかかっていた記憶があります。

今は順位が落ちたとかではなく、いくらスクロールしても、いくらページをめくってもGoogleの検索結果に表示されません（インデックスにはちゃんと登録されているのに！）。
僕はこの結果に「お前のブログは絶対に表示させないぞ」というGoogleの強い意志を感じます。

個人ブログもたくさん検索結果に上げてくれるBing

Googleがどういうルールでランク付けしているのかはわからないので、もしかすると僕のブログが何らかの理由でペナルティーを食らってたりするのかもしれません（Google Search Consoleの内容は特に問題なさそうなんですけどね）。
ですが、僕だけに限らず、Googleで検索すると個人ブログが引っかかる割合が最近減ってきたような気がしています。

そういう不信感のようなものがGoogleに対して芽生えてきた頃にBingを試してみたところ、昔のGoogleっぽいというか、個人ブログも含めて分け隔てなく検索結果に表示してくれているような印象を受けました。
なので、それ以来、メインの検索エンジンはBingを使うようにしています。

僕は人の役に立ちたくてブログを書いてるのに！！

昔から僕は自分が情報発信することで他の人の役に立ちたい、という思いでブログやQiitaの記事を書いています。
上の例で挙げたワイパー交換の記事にしても、「これならすぐわかる」という交換方法がネットに見つからなかったので、今後自分と同じように自分でワイパー交換したいと思った人のためにブログを書きました。
これはギター弦のブログ記事も同様です。

しかし、Googleは（何か特定のルールに従ってキーワードを入れないと）僕のブログを表示してくれません。
これだと「XC60のワイパーを自分で交換したい」とか「FGNのフルアコにThomastikの弦を張りたい」と思った人が僕のブログにたどり着けなくなってしまいます。

個人が情報発信することでニッチな情報もネットなら見つかる、というのがインターネットの大好きなところだったのに、最近のGoogleは個人ブログを意図的に排除しているような、そんな雰囲気を感じて少し悲しいです 😢

まあ、時代が変わったんだよと言われたらそれまでなのですが、ネットの検索エンジンはGoogleだけがすべてではないので、僕はインターネットの良心を忘れていない（と勝手に信じている）Bingに乗り換えたのでした。

Bingのイマイチなところ

Googleに比べて個人ブログも検索結果に上げてくれやすいのがBingのいいところですが、イマイチなところもいくつかあります。

スクロールが強制的にトップに戻ることがある

意図せず検索結果画面のスクロールがトップに戻っていて、イラッとすることがたまにあります。
具体的にはこんな感じです。

検索結果を表示する
　↓
下の方にスクロールする
　↓
リンクを別タブで開く
　↓
リンク先のページを閲覧したあと、Bingの検索結果にまた戻る
　↓
なぜかスクロールがトップに戻っている
　↓
また下までスクロールしないといけない！ 💢

別タブで開く表示にしているのに同じタブで開くことがある

検索結果のリンクをクリックしたときは別タブで開く設定にしているんですが、たまに同じタブで開くことがあります。
設定の意味ないやん！なんで？って思います……。

1ページあたりの表示件数を増やせない

検索結果は1ページあたり最大10件程度です。
設定で変更できないので、知りたい情報が上位に出てこないときは何度もページ送りしないとといけません。

広告と検索結果の区別がしづらい

広告は小さな字で「広告」って書いてあるだけで視覚的な違いが少ないため、よーく確認しないと広告をクリックしそうになってしまいます。

とはいえ、検索エンジンは検索結果がすべてでしょ！！

こんな感じでBingはUX（ユーザー体験）としては、ちょっとイケてない部分も多いです。
ですが、検索エンジンで大事なのは検索結果です。

個人ブログの表示順位を下げるのではなく、（検索キーワードによっては）個人ブログをまったく表示しないというGoogleの方針がどうしても好きになれないので、僕はまだしばらくBingを使い続けるつもりです。

まとめ

というわけで、今回のエントリではメインの検索エンジンをGoogleからBingに変えた理由を書いてみました。
いつの頃からは「検索エンジンといえばGoogle」と決まっていましたし、僕自身もそう考えていましたが、この1年ぐらいで僕はGoogleの検索結果に対して強い違和感と不信感を感じるようになりました。

僕みたいに「個人による情報発信を読むのが好き」という人は、Bingに切り替えてみると昔の大好きだったインターネットが帰ってくるかもしれませんよ？

あわせて読みたい

僕がアウトプットするのは「インターネットに恩返し」したいからなんです！という話を書いた記事です。
こちらもあわせてどうぞ。
levtech.jp