Die größten Fehler beim Software-Blogging

In manchen Wochen habe ich das Gefühl, dass die Mehrheit der Software-Blogs, die ich sehe, inzwischen von LLMs geschrieben sind. Sie sind meistens furchtbar.

Vielleicht kann jemand den LLMs von diesen Anti-Patterns erzählen, im Ernst, würde das helfen?

Ich würde es natürlich bevorzugen, wenn die Leute den Text, von dem sie erwarten, dass ich ihn als Mensch lese, einfach selbst schreiben würden.

"Die mäandernde Einleitung" ist wohl der mit Abstand häufigste Fehler, aber der mit Abstand schädlichste Fehler ist das Versäumnis, das Thema mit etwas zu verbinden, womit die Leser vertraut sind (Anti-Pattern #2). Manche Dinge erfordern einfach ein bestimmtes Maß an Expertise/Voraussetzungen, um überhaupt anfangen zu können, sie zu verstehen, aber ich habe im Software-Blogging, in READMEs usw. immer wieder gesehen, dass die Frage nicht beantwortet wird: "Was ist das, verglichen mit dem, womit ich vertraut bin, und wenn ich mit nichts Relevantem vertraut bin, warum sollte ich das dann wollen?"

Das gilt für fast alles im Software-Bereich. Neues Tool? Neues Design Pattern? Neue Library? Sprach-Idiom? Sprache? Oder, für modernere Betrachtungen, neues Modell? Neues Harness? Neue Harness-Option? Neues Nutzungsmuster? Gib eine kurze Zusammenfassung davon, wie ein Projekt ohne es aussieht, um das Problem zu vermitteln, das allein seine Existenz löst. Dann gehe ins Detail, wie es sich mit anderen Lösungen vergleichen könnte.

Vielleicht ist es einfach eine spezifische Art, wie mein Gehirn funktioniert, dass es diese Art von Information intuitiv findet und das Fehlen besonders nervig.

Das ist mit Abstand die größte Herausforderung, auf die man beim Schreiben eines Tutorials, einer Videospiel-Komplettlösung, eines Rezepts usw. stößt:

> "Der Leser weiß alles, was ich weiß, außer dieser einen Sache"

Denn wie der Artikel sagt, ist es schwer zu wissen, was das Publikum bereits weiß, und viel zu leicht, beim Helfen 'Abkürzungen' zu nehmen, indem man vergisst, wie viele Dinge man ins Muskelgedächtnis verschoben hat.

Menschen etwas beizubringen ist schwierig, und es ist wirklich leicht, eine Menge entscheidender Informationen auszulassen, wenn man nicht aufpasst.

Allerdings habe ich hier auch noch ein weiteres Anti-Pattern (und ein weiteres empfehlenswertes Design Pattern), das es wert ist, in Betracht gezogen zu werden.

Beim Anti-Pattern geht es darum, dass das Tutorial wegen Aktualisierungen des betreffenden Themas nicht mehr funktioniert. Ich erinnere mich, dass das ein großes Problem war, als ich vor ein paar Jahren versuchte, Angular zu lernen, da das offizielle Tutorial offensichtlich für eine längst veraltete Version des Frameworks geschrieben worden war, die ganz anders funktionierte als die aktuelle.

Die Anzahl der Male, bei denen ich online solche Probleme hatte, ist viel zu hoch, und meist liegt es daran, dass die Person, die das Tutorial geschrieben hat, nicht nachgeschaut hat, wann immer die Sprache, das Framework oder relevante Abhängigkeiten ein größeres Update bekamen.

Also, wenn du über ein Thema schreibst und sich die Dinge erheblich ändern, geh zurück und überprüfe deine frühere Arbeit. Wenn du kannst, aktualisiere den Artikel, und wenn du nicht kannst, setze zumindest oben einen Hinweis, dass der Artikel jetzt veraltet ist und übersprungen werden sollte.

Nebenbei bemerkt, ein gutes Muster, das man im Auge behalten sollte, ist, dass man nicht ne […]

Ich würde sagen, das alles läuft auf Empathie hinaus. Denk darüber nach, wer dein Zielpublikum ist, und schreibe für die am wenigsten informierten unter ihnen.

Es ist in Ordnung, bei seinem Zielpublikum selektiv zu sein. Die meisten von uns schreiben sowieso kostenlos, also verlieren wir keine Einnahmen, wenn wir in einem Artikel über die Optimierung des LLM-Durchsatzes nicht erklären, was ein Computer ist. Vielleicht schreibst du für andere Engineers, die mit dem Thema vertraut sind, aber nicht mit den Besonderheiten deines Projekts.

Stelle das Wichtigste über den Falz. Wenn du in den ersten 10 Sekunden die Aufmerksamkeit von jemandem erregst, kauft dir das weitere 30.

Füge Visuals hinzu. Kästen und Pfeile, Diagramme, Videos, wo angebracht.

Wenn du unbedingt eine mäandernde Erzählung schreiben musst, setze sie ans Ende, nicht an den Anfang.

Letzte Woche, nachdem ich einem HN-Link gefolgt war, dachte ich, dass Tech-Blogs langsam diesen "Jump to Recipe"-Link brauchen, der die Welt des Food-Bloggings übernommen hat (zum Besseren).

"Die mäandernde Einleitung"

Nicht nur die Einleitung. Viele Blogger versuchen zu schreiben, als würden sie eine Geschichte schreiben, Spannung aufbauen und so weiter. Beim technischen Schreiben sollte man die Kernaussage nicht vergraben.

"Do this not that"-Listen sind immer kontext- und situationsabhängig. Einiges davon ergibt Sinn im Kontext einer professionellen oder geschäftlichen Website, aber stelle sicher, dass deine Ziele übereinstimmen, bevor du den Rat annimmst.

Wenn du in deinem persönlichen Blog schreibst, dann nimm das alles mit der Größe eines Salzkristalls, die du für angemessen hältst. Persönlich ist das etwa die Größe eines Acme-Tresors, der über einer Klippe hängt und auf einen ahnungslosen Listicle-Autor^h^hKojoten wartet.