ソフトウェアブログでやりがちなアンチパターン集

最近は、目にするソフトウェアブログの大半がLLMによって書かれているように感じる週もある。それらはたいていひどい。

誰かLLMにこれらのアンチパターンを教えてやれる人はいないだろうか、真面目な話、効果はあるのだろうか？

もちろん、私という人間が読むことを期待するテキストは、人間自身が実際に書いてくれた方がいい。

「とりとめのない導入」は、おそらく断然最もよくある間違いだが、断然最も有害な間違いは、話題を読者がよく知っている何かと結びつけることに失敗することだ（アンチパターン#2）。理解し始めるには一定の専門知識や前提条件が単純に必要なものもあるが、ソフトウェアブログやREADMEなどで、「これは何か、私がよく知っているものと比べてどうか、そして関連するものを何も知らないなら、なぜ知りたくなるべきなのか」に答えられていないのを何度も見てきた。

これはソフトウェア分野のほとんどすべてに当てはまる。新しいツール？新しいデザインパターン？新しいライブラリ？言語のイディオム？言語？あるいはより現代的な見方なら、新しいモデル？新しいハーネス？新しいハーネスオプション？新しい使用パターン？それが存在しない場合のプロジェクトがどんなものか簡単に要約し、その存在自体が解決している問題を伝えよ。それから、他の解決策とどう比較されるかの詳細に入る。

おそらくこれは、私の脳がこの種の情報を直感的だと感じ、それが欠けていると特に苛立つという、特定の働き方なのかもしれない。

これは、チュートリアル、ビデオゲームの攻略、レシピなどを書くときに遭遇する、断然最大の課題だ：

> 「読者は、この一つのこと以外は私が知っていることをすべて知っている」

記事が言うように、読者がすでに何を知っているかを知るのは難しく、助けるときに「近道」をして、どれだけ多くのことを筋記憶に任せてきたかを忘れてしまうのはあまりにも簡単だからだ。

人に教えるのは難しく、注意しないと多くの重要な情報を簡単に省いてしまう。

とはいえ、ここで考慮に値するアンチパターンがもう一つ（そして推奨デザインパターンがもう一つ）ある。

アンチパターンとは、対象の更新によってチュートリアルがもう機能しなくなる場合だ。数年前にAngularを学ぼうとしたとき、公式チュートリアルが明らかに、現在とは大きく異なる機能を持つ、とうに時代遅れのバージョンのフレームワーク向けに書かれていたので、これは大きな問題だったのを覚えている。

そのような問題に遭遇した回数はオンラインではあまりにも多く、たいていは、言語、フレームワーク、または関連する依存関係がメジャーアップデートされるたびに、チュートリアルを書いた人がそれを見直さなかったからだ。

だから、あるトピックについて書いて、物事が大きく変わったなら、以前の自分の仕事を振り返って確認せよ。できれば記事を更新し、できなければ少なくとも記事は今や時代遅れでスキップすべきだという注意を冒頭に置け。

別の話だが、心に留めておくべき良いパターンは、あなたは必ずしも…［以下略］

これらはすべて共感に帰着すると思う。ターゲット読者が誰かを考え、その中で最も知識の少ない人のために書く。

ターゲット読者を選ぶのは構わない。ほとんどの人はどうせ無料で書いているので、LLMスループットの最適化に関する記事でコンピュータとは何かを説明しないからといって収入を失うわけではない。あなたは、トピックには詳しいがあなたのプロジェクトの細部には詳しくない他のエンジニアに向けて書いているのかもしれない。

最も重要なものを折り返しの上に置け。最初の10秒で誰かの注意を引ければ、さらに30秒を稼げる。

視覚資料を加えよ。ボックスと矢印、チャート、適切な場合は動画。

どうしてもとりとめのない物語を書かなければならないなら、それは冒頭ではなく最後に置け。

先週、HNのリンクをたどった後、テックブログにも、フードブログ界を（良い方向に）席巻したあの「レシピへジャンプ」リンクが必要になり始めていると感じた。

「とりとめのない導入」

導入だけではない。多くのブロガーは、物語を書くように、サスペンスを盛り上げながら書こうとする。技術文書では、肝心なことを埋もれさせるな。

「これをやれ、あれはやるな」リストは常に文脈依存で状況次第だ。これの一部はプロフェッショナルやビジネスサイトの文脈では理にかなうが、アドバイスを受け入れる前に自分の目標が合致しているか確認せよ。

個人ブログで書いているなら、このすべてを自分が妥当だと感じる大きさの塩の結晶とともに受け取れ。個人的には、それは崖の上で無防備なリスト記事ライター^h^hコヨーテを待ち構えるアークメ金庫くらいの大きさだ。