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

ソフトウェア開発では、ソフトウェアにおける悪い結果につながる一般的な特徴を認識するためにアンチパターンを収集します。 ソフトウェアブログについても同様のことを行うと役立つと考えたので、初心者ブロガーがよく犯す間違いをカタログ化しました。 導入がさまよう 前置きもさまよっているとみなされる 「読者は、私が知っていることすべてを知っているが、この一つのことだけは知らない」 リンクへの過度の依存 続編注入バグ 過度の形式ばった態度 レンダリングHTMLの基本でつまずく モバイルでのページオーバーフロー 読みにくいフォント 導入がさまよう ソフトウェアブログで最も一般的な間違いは、圧倒的にさまようことです。 著者が何を伝えようとしているのか、数段落読んでもわからない記事にしょっちゅう遭遇します。 開発者は具体性を好むため、ブログ記事を背景談話、歴史的文脈、あるいは頭に浮かんだその他のもので始めがちです。 それは書くのは楽しいかもしれませんが、読む側にとって常に興味深いとは限りません。 読者の視点からすると、他に読むべき記事は無数にあります。 なぜあなたの記事を読むべきなのでしょうか？ 見返りが期待できない限り、20分かけて全文を読むつもりはありません。 読者に、読み続ける理由を与えましょう。 開発者がブログ記事を読み始めるとき、できるだけ早く次の2つの質問に答えようとしています。 著者は私のためにこの記事を書いたのか？ この記事を読むことでどのような利益が得られるのか？ 両方の質問に答えるために、タイトルと最初の3文を使いましょう。 読者に提供できる利益とは、新しいスキルを教えること、概念を説明すること、新しい視点を示すこと、あるいは面白い愚痴を届けることなどです。 とにかく読者に何かを提供しなければなりません。 記事があるというだけで、読者はあなたのブログ記事を読んでくれるわけではありません。 以下は私が最近書いた、要点を押さえた記事です。 ✓良い 読者に記事がどのように役立つかを示して記事を始める 「Goのテストをより良く書くための簡単な方法」 優れたGoのテストパターンがありますが、知っている人はほとんどいません。 30秒で教えることができます。 この導入部は、この記事がGoプログラミング言語を使用するプログラマーに関連しており、価値は彼らがすぐに学べる新しいテクニックを教えることであることを簡潔に伝えています。 前置きもさまようとみなされる 一部のブロガーは魅力的な導入部を書きますが、副題、著者紹介、画像、有名な引用などの余分なもので読者の道を妨げます。 これらのいずれを含めることはできますが、それらが「読者を読み続けさせる」予算を消費することを認識してください。 読者の道に置くものすべてが、彼らの限られた集中力を削る追加の作業です。 ✗悪い 過剰な前置きを読者に読ませる 「読者は、私が知っていることすべてを知っているが、この一つのことだけは知らない」 効果的な教師は、読者が慣れ親しんでいるものと比較して新しい概念を説明します。 例えば、Jellyfinを説明する場合、「JellyfinはNetflixのようなストリーミングサービスですが、オープンソースでプライベートなので、誰もあなたの視聴習慣を監視しません」と言うかもしれません。 難しいのは、読者が慣れ親しんでいるものを知ることです。 ✗悪い 読者があなたと同じ知識を持っていると仮定する この記事では、Dockerを初めて聞く開発者にDockerを紹介します。 Dockerはシンプルです。 Linuxのcgroupsに対する洗練されたフロントエンドにすぎません。 ああ、*BSDの jailsを知っていますか？ DockerはそれのLinux版です。 多くの開発者はDockerを使いたいと思っていますが、cgroups、jails、*BSDのような用語を認識していません。 彼らはLinuxが何であるかさえ知らないかもしれません、特にDockerの紹介を探している場合。 読者があなたの持つ正確な知識を持っていると仮定するのではなく、読者に対するあなたの仮定を最小限に抑えましょう。 ✓良い 読者の背景知識に関する仮定を最小限にする。 Dockerは、どこで実行されても一貫性があり再現可能な環境を持つようにアプリをパッケージ化するためのツールです。 Dockerを使用すると、アプリの環境と依存関係を人間が読めるテキストファイルで定義できます。 これらのファイルはアプリの要件をキャプチャするため、たとえ長年異なるチームによって調整されたとしても、アプリがどのように機能するかを正確に把握できます。 ブログ記事を書くときは、ターゲット読者を考えてください。 彼らは何を知っていますか？ 現実の友人やチームメイトを想像してください。 その読者が認識するであろう用語と認識しないであろう用語のリストを作成します。 次に、ブログ記事を再読し、技術用語に遭遇するたびに、参照読者がそれを理解できるかどうかを考えてください。 あなたは私が念頭に置いていた読者層を説明していますが、私はその読者層が何を知っているかをリストアップしたことはありませんでした。 あなたのリストと私のドラフトの仮定を比較するのは非常に驚くべきことです。 – Tyler Cipriani、「Gitにおける大規模ファイルの将来」を編集する際に、ターゲット読者に関する仮定について異議を唱えたとき リンクへの過度の依存 最後に、読者に読むのをやめて、別の本を買いに行き、それをすべて読んでから、元の本を続けるように指示する本を読んだのはいつですか？ ソフトウェアブロガーはこれを常にやっていますが、それはより微妙です。 ブロガーは、読者が知らないかもしれない用語に言及したいことがよくありますが、自分で説明する手間を省きたいと思っています。 代わりに、その用語にリンクを貼り、「問題解決！」と考えます。 読者は流れを中断して、一つの単語を理解するためだけに別のサイト全体を読みたいとは思わないので、問題は解決されません。 ✗悪い 読者に用語を説明するためにリンクに依存する 外部トラフィックがデータベースに到達するのを防ぐためにファイアウォールルールを割り当てます。 上記でリンクされているFreeBSDマニュアルは優れたリソースですが、ファイアウォールに関する章は約20,000語です。 これほど単語数の多いページにリンクすると、読者に大量の作業を課すことになります。 リンクに頼って作業を肩代わりさせるのではなく、記事を理解するために必要な最小限の説明を読者に提供してください。 ✓良い リンクの背後にある関連情報を要約する ファイアウォールは、ホストとネットワークの通信方法をアプリに制限するシステムです。 ファイアウォールルールを設定して、アプリサーバーから発信された場合にのみデータベースサーバーへの着信リクエストを許可するようにすることで、Webアプリのセキュリティを強化できます。 有用なリソースへのリンクはぜひ提供してください、しかしそれらは必須ではなくボーナスにしてください。 読者をページに留めておきましょう。 ターゲット読者は、リンクをクリックせずに最初から最後まで記事を楽しんで理解できるはずです。 続編注入バグ 最近では、ブログ記事も含め、すべてが続編かリブートです。 多くのブログ記事がこのように始まります。 パート1では、五重連結リストとそれが日々のLOC出力を100倍にする方法について学びました。 今日の記事では、goto文がどのように「スクランクマックス」（パート1で私が発明した用語です。覚えていますか？）を可能にするかを示します。 残念ながら、ほとんどの読者はパート1を読んでいません。 前の記事が読者の記憶に鮮明に残っていると仮定すると、彼らは「ああ、読み始めるためだけに余分な作業があるのか？」と思うでしょう。 過去の記事を参照するのは構いませんが、最初からそうしないでください。 過去の記事にリンクする場合は、読者に戻って全文を読むように強制するのではなく、関連する内容を要約してください。 自作のホビーオペレーティングシステムについて書いているのであれば、確かに1つのブログ記事では足りないかもしれませんが、続編記事の大部分は、3%程度の努力で独立した記事にできるはずです。 過度の形式ばった態度 初心者ソフトウェアブロガーは、真剣に受け取られるためには、堅苦しく過度に形式ばった方法で書かなければならないという集団的な妄想に悩まされています。 このプロジェクトの期間中、私のチームメイトと私はいくつかの静的解析ツールを使用しました。 あなたは1988年のIBMの80歳の役員のために書いているのではありません。 あなたの分野はソフトウェア開発であり、最も気取らないホワイトカラーの仕事の一つです。 あなたの記事を読んでいる人は、おそらくパジャマとビーチサンダルを履き、キーボードの横でシリアルを食べながら読んでいるでしょう。 彼らはあなたが法律文書のように話すことを期待も望みもしません。 話すように書きましょう。 ✓良い 話すように書く このプロジェクトでいくつかの静的アナライザーを試しました。 多くの開発者がAIに執筆を委任しているため、ソフトウェアブログはますます