HN 日本語サマリー

← 一覧へ戻る
キャリア

ソフトウェアブログにおけるアンチパターン

Anti-Patterns in Software Blogging (refactoringenglish.com)

283 pointsby ilreb140 コメント

要約

ソフトウェア開発におけるアンチパターンと同様に、ソフトウェアブログにも読者の離脱を招く一般的な間違いが存在します。記事の冒頭で読者の疑問(誰向けか、どう役立つか)に答えること、専門用語の過度な使用を避け、読者の知識レベルを考慮すること、リンクに頼りすぎず記事内で完結させること、そして堅苦しすぎない自然な言葉遣いが重要です。これらのアンチパターンを避けることで、より効果的なブログ記事を作成できます。

全文翻訳

ソフトウェアブログにおけるアンチパターン

ソフトウェア開発では、ソフトウェアに悪い結果をもたらす一般的な特徴を認識するためにアンチパターンを収集します。ソフトウェアブログについても同様のことを行うと便利だと考え、初心者ブロガーがよく犯す間違いをカタログ化しました。

冗長な導入🔗

ソフトウェアブログで最もよくある間違いは、圧倒的に冗長な導入です。私は、記事を数段落読んだ後も、著者が何を伝えたいのか全く分からないという状況に頻繁に遭遇します。

[画像:開発者がトップパネルを積み重ねて読む様子]

開発者は具体性を好むため、ブログ記事の冒頭に背景情報、歴史的文脈、あるいは頭に浮かんだその他のことを書きがちです。書くのは楽しいかもしれませんが、読む側にとって常に面白いとは限りません。

読者の視点から見ると、他に読むべき記事は無数にあります。なぜあなたの記事を読む必要があるのでしょうか?読者は、見返りが期待できない限り、20分かけて全文を読むことをいとわないでしょう。読者に読み進める理由を与えてください。

開発者がブログ記事を読み始めるとき、彼らはできるだけ早く2つの質問に答えようとしています。

  1. 著者は私のためにこの記事を書いたのだろうか?
  2. この記事を読むことでどのような利益が得られるだろうか?

タイトルと最初の3文で、これらの両方の質問に答えてください。

提供できる利益とは、読者に新しいスキルを教えること、概念を説明すること、新しい視点を示すこと、あるいは面白い愚痴を届けることなどです。読者に何かを提供する必要があります。記事があるというだけで、読者はあなたのブログ記事を読んでくれるわけではありません。

ここに私が最近書いた記事があります。要点に直接入っています。

got, want: より良いGoテストを書くためのシンプルな方法

あまり知られていない優れたGoのテストパターンがあります。30秒で教えることができます。

この導入は、Goプログラミング言語を使用するプログラマーに関連する記事であり、その価値は、彼らがすぐに学べる新しいテクニックを教えることであることを簡潔に伝えています。

前置きも冗長とみなされる🔗

一部のブロガーは魅力的な導入を書きますが、サブタイトル、著者紹介、画像、有名な引用などの余分なもので読者の道を妨げます。これらの要素を含めることはできますが、それらが「読者を読み進めさせる」という予算を圧迫することを認識してください。読者の道に置くすべてのものは、彼らの限られた集中力を削る追加の作業です。

[画像:前置きが多すぎる]

「読者は私が知っていることをすべて知っていて、この一つのことだけが知らない」🔗

効果的な教師は、新しい概念を読者が慣れ親しんでいるものと比較して説明します。例えば、Jellyfinを説明する場合、「JellyfinはNetflixのようなストリーミングサービスですが、オープンソースでプライベートなので、誰もあなたの視聴習慣を監視しません」と言うかもしれません。難しいのは、読者が何に慣れ親しんでいるかを知ることです。

この記事では、Dockerを全く知らない開発者にDockerを紹介します。

Dockerはシンプルです。Linux cgroupsのスリックなフロントエンドにすぎません。ああ、 you know jails in *BSD? Docker is the Linux version of that.

多くの開発者はDockerを使いたいと思っていますが、cgroups、jails、*BSDのような用語を認識していません。Dockerの導入を探している場合、Linuxが何であるかさえ知らないかもしれません。

[画像:読者の脳]

読者があなたと同じ知識を持っていると仮定するのではなく、読者に関するあなたの仮定を最小限に抑えてください。

Dockerは、アプリケーションをパッケージ化するためのツールであり、どこで実行されても一貫性があり再現可能な環境を提供します。Dockerを使用すると、人間が読めるテキストファイルでアプリケーションの環境と依存関係を定義できます。これらのファイルはアプリケーションの要件をキャプチャするため、長年にわたる異なるチームによる変更の後でも、それがどのように機能するかを正確に把握できます。

ブログ記事を書くときは、ターゲット読者を考えてください。彼らは何を知っていますか?現実の友人やチームメイトを想像してください。彼らが認識できる用語と認識できない用語のリストを作成します。次に、ブログ記事を再読し、技術用語に出くわしたら、参照している読者がそれを理解できるかどうかを考えてください。

あなたが念頭に置いている読者層を描写してくれていますが、その読者層が何を知っているかをリストアップしたことはありませんでした。私の下書きの仮定とあなたのリストを比較するのは、非常に驚くべきことです。

– Tyler Cipriani、編集中に彼のターゲット読者に関する仮定について私が異議を唱えたとき 「Gitにおける大規模ファイルの未来はGit」

リンクへの過度な依存🔗

最後に、読者に読むのをやめて、別の本を買いに行き、それを全部読んでから元の本を続けるように指示する本を読んだのはいつですか?ソフトウェアブロガーはこれを常にやっていますが、それはより微妙です。

ブロガーは、読者が知らないかもしれない用語に言及したいことがよくありますが、自分で説明する気はありません。代わりに、その用語にリンクを貼り、「問題解決!」と考えます。

読者は一つの単語を理解するために、流れを中断して全く別のサイトを読みに行くことを望まないため、問題は解決されません。

外部トラフィックがデータベースに到達しないように、ファイアウォールルールを割り当てます。

上記でリンクされているFreeBSDマニュアルは優れたリソースですが、ファイアウォールに関する章は約20,000語です。そのような単語数の多いページにリンクすると、読者に大量の作業を課すことになります。

リンクに頼って作業を任せるのではなく、記事を理解するために必要な最小限の説明を読者に提供してください。

ファイアウォールは、ホストとネットワークがアプリケーションと通信する方法を制限するシステムです。Webアプリケーションサーバーからのリクエストのみがデータベースサーバーに到達するようにファイアウォールルールを設定することで、Webアプリケーションのセキュリティを向上させることができます。

有用なリソースへのリンクはいくらでも構いませんが、それらは必須ではなく、ボーナスとしてください。読者をページに留めておきましょう。ターゲット読者は、リンクをクリックすることなく、最初から最後まで記事を楽しんで理解できるはずです。

続編注入バグ🔗

最近では、ブログ記事を含め、すべてが続編またはリブートです。多くのブログ記事が次のように始まります。

パート1では、五重連結リストと、それが日々のLOC出力を100倍にする方法について学びました。今日の記事では、goto文がどのようにして(パート1で私が発明した用語である「スクランクマックス」を)可能にするかを示します(覚えていますか?)。

残念ながら、ほとんどの読者はパート1を読んでいません。前の記事が読者の記憶に鮮明に残っていると仮定すると、彼らは「ああ、読み始めるだけでも追加の作業があるのか?」と思うでしょう。

過去の記事を参照することは問題ありませんが、最初からそうしないでください。過去の記事にリンクする場合は、読者にすべてを読み返すように強制するのではなく、彼らが知る必要がある関連情報を要約してください。

自作のオペレーティングシステムについて書いているのであれば、確かに1つのブログ記事では足りないかもしれませんが、続編記事の大多数は、3%程度の追加努力で単独の記事になり得ます。

過剰な丁寧さ🔗

初心者ソフトウェアブロガーは、真剣に受け取ってもらうためには、堅苦しく過度に丁寧な方法で書かなければならないという集団的妄想に苦しんでいます。

このプロジェクトのライフタイムを通じて、私のチームメイトと私はいくつかの静的解析ツールを利用しました。

あなたは1988年のIBMの80歳の役員のために書いているのではありません。あなたの分野はソフトウェア開発であり、最も気取らないホワイトカラーの仕事の一つです。あなたの記事を読んでいる人は、おそらくパジャマとビーチサンダルを履き、キーボードの隣でシリアルを食べながら読んでいるでしょう。彼らはあなたが法律文書のように話すことを期待も望んでもいません。

話すように書きましょう。

このプロジェクトでは、いくつかの静的アナライザーを試しました。

多くの開発者がAIに執筆を委任しているため、ソフトウェアブログは味気なく均一になっています。読者は個性のある文章に飢えています。これは、史上最高のソフトウェアブロガーであるJoel Spolskyからのランダムな一文です。

高校でBASICを使ってApple IIでポンゲームを書いていた優秀な子供たちは、大学に入り、CompSci 101、データ構造のコースを受講し、ポインターのビジネスにぶつかったときに、彼らの脳は完全に爆発し、次の瞬間には政治学専攻になっていました。なぜなら、法科大学院の方が良い考えのように思えたからです。

– Joel Spolsky, “The Perils of JavaSchools”

これはSpolskyの最高の発言ではありませんが、彼のスタイルを捉えています。カジュアルで、親しみやすく、気取らない。まるでランチで友人に物語を話しているかのようです。Kathy Sierra、Terence Eden、Raymond Chenの文章にも同じスタイルが見られます。彼らは賢く聞こえようとしているのではなく、自分らしく聞こえようとしているだけで、それが読者が楽しむものです。

HTMLレンダリングの基本をしくじる🔗

ソフトウェアブログで最も難しいのは、魅力的な文章を書くことなので、多くのソフトウェアブロガーが、本来簡単なはずの部分、つまり基本的なウェブページを作成することを台無しにしているのを見ると、イライラします。

モバイルでのページオーバーフロー🔗

モバイル読者にとって犯しうる最悪の間違いは、画面からはみ出してしまい、読者が記事を読むために前後にスクロールしなければならなくなることです。通常、これはデスクトップサイズを主張する画像やコードスニペットがあり、ページのレイアウトを台無しにするためです。

[動画:お使いのブラウザは動画タグをサポートしていません。]

モバイルでテキストが画面からはみ出すのを許すと、悲惨な読書体験が生まれます。

FirefoxとChromeのデスクトップバージョンには、どちらもモバイルプレビューモードがあります。公開前にモバイルプレビューで記事を確認し、一般的なレンダリングの問題がないかチェックしてください。

モバイル読者を過小評価しないでください。私の分析によると、25%の読者がこのページをスマートフォンで読んでいます。私の個人的なブログでは35%です。

読みにくいフォント🔗

読みやすいフォントの色とファミリーを選択してください。明るい灰色の背景に暗い灰色のテキストはやめてください。FirefoxとChromeには、コントラストの低いテキストをフラグ付けする組み込みツールがあります。

[画像:コントラストの低いテキスト]

Firefoxのアクセシビリティツールがコントラストの低いテキストを特定しています

完璧なフォントを探すのが面倒な場合は、Braille InstituteがAtkinson Hyperlegibleという無料フォントを提供しており、視力の弱い読者でも特に快適に読めます。

まとめ🔗

  • 読者が読み進める説得力のある理由を与えてください。ブログ記事のタイトルと最初の3文でそれを提示してください。
    • 一般的な理由:面白い話を聞きたい、役立つテクニックを学びたい、または自分に関連する概念を理解したい。
  • 読者が知っていること、知らないことについての仮定を問い直してください。
    • 読者が認識できると期待する概念や用語を考え、記事を再読して、それらの期待と一致しているか確認してください。
  • 読者は、リンクをクリックしたりツールチップをホバーしたりすることなく、記事を最初から最後まで読めるべきです。
    • リンクは読者がトピックをさらに深く探求できるようにするべきですが、必須ではなくボーナスであるべきです。
  • 記事を以前の記事の続編として提示することは避けてください。
    • ほとんどの読者は以前の記事を読んでいないと仮定してください。読者に過去の記事をすべて読んでもらうことを期待するのではなく、彼らが知る必要がある関連情報を要約してください。
  • 丁寧すぎるのをやめましょう。現実の自分で話すように書きましょう。
  • ブラウザのモバイルビューで記事をテストしてください。
    • テキストが画面からはみ出して、読者が読みながら水平方向にスクロールしなければならないようなことがないようにしてください。
  • ブラウザのテストツールを使用して、記事を読むのを難しくするコントラストの低いテキストを見つけてください。

「Not Quite How Developers Read」と「What the Reader Knows」のイラストは Piotr Letachowicz によるものです。