Schreiben von technischen Blogbeiträgen über Coding-Projekte

Man könnte sagen, dass das Schreiben von Code einfacher ist als das Schreiben über Code. Code funktioniert entweder oder er funktioniert nicht, während natürliche Sprache auf alle möglichen Arten scheitern oder erfolgreich sein kann. Aber wenn Sie ein guter Programmierer sind, haben Sie die meisten Fähigkeiten, die Sie brauchen, um bei dieser anderen Art des Schreibens erfolgreich zu sein, und andere Entwickler können davon profitieren, dass Sie Ihre Ideen teilen.

Das Schreiben eines Blogbeitrags ist ähnlich wie das Schreiben von Code:

• Sie entwickeln eine Idee und skizzieren, wie Sie vom Nichts zu ihrer vollständigen Umsetzung gelangen wollen.

• Sie befolgen syntaktische Regeln, um Fehlinterpretationen zu vermeiden.

• Sie bemühen sich, ausführlich genug zu sein, um verstanden zu werden, und gleichzeitig zu vereinfachen, wo immer es möglich ist.

Wenn Sie schreiben über Code schreiben, gibt es zusätzliche Techniken, die Sie anwenden können. Aber es hilft auch, sich darauf zu konzentrieren, was der Leser von Ihrem Beitrag erwartet. Ein Vorteil von technischen Blogbeiträgen gegenüber anderen Arten von Texten ist, dass die Wünsche des Lesers in der Regel ziemlich offensichtlich sind.

Effektives technisches Schreiben

Das Problem ist, dass technische Texte trocken sind. Verschiedene Leute haben viele verschiedene Strategien, um das zu mildern, aber clevere Tricks können an dieser zentralen Tatsache nichts ändern. Das Lesen abstrakter Erklärungen von Algorithmen und Syntax ist eine schwierige Aufgabe. Das Gehirn -insbesondere das Gedächtnis-funktioniert, indem es Assoziationen herstellt, und technische Informationen bieten nur wenige Anknüpfungspunkte für diese Assoziationen.

Das gilt nicht nur für das technische Schreiben. Wenn Sie schon einmal Schwierigkeiten hatten, während einer halbstündigen Vorlesung oder eines Konferenzgesprächs wach zu bleiben, aber kein Problem damit haben, sich auf einen zweistündigen Film zu konzentrieren, wissen Sie das bereits. Langeweile hat weniger mit den Personen zu tun, die Informationen erhalten, als mit der Art und Weise, wie sie präsentiert werden.

Warum lesen Menschen technische Blogbeiträge? Meistens wollen sie wissen, wie sie eine Aufgabe erledigen können, oder sie wollen sich in ein bestimmtes Thema vertiefen. Die Herausforderung besteht darin, dieses Bedürfnis zu befriedigen, bevor die Aufmerksamkeitsspanne der Leser zu Ende ist.

Technische Texte lassen sich fast immer verbessern, wenn sie weniger lang sind. Das gilt sowohl für die Länge des Beitrags als auch für die Länge der Sätze. Es gilt sogar für die Codebeispiele, die Sie verwenden. Technische Informationen zu konsumieren ist schon eine Herausforderung für unser Gehirn. Sie können den Lesern helfen, Ihr Thema zu verstehen, indem Sie die Informationen für sie nach Prioritäten ordnen und alles Unwichtige weglassen.

Es gibt viele verschiedene Methoden, um die verbleibende Schrift zu erleichtern. Einige effektive Werkzeuge sind:

• Humor

• Anthropomorphisierung von Concepts oder Code

• Bilder (GIFs, keine Kuchendiagramme)

• Interaktive Beispiele

• Code

• Aufzählungslisten

Einige dieser Techniken wirken sich auf das Schreiben selbst aus, andere sorgen für eine Pause davon. Aber sie alle nutzen andere Teile des Gehirns als den Teil, der sich Formeln und Algorithmen merkt. Erinnerungen bestehen aus Verknüpfungen zwischen Teilen des Gehirns, und sich an die Dinge zu erinnern, die man gerade liest, ist der Schlüssel, um geistige Erschöpfung lange genug zu vermeiden, um das große Ganze zu verstehen.

Wenn Sie noch nicht viel über technische Themen geschrieben haben oder noch nicht viel geschrieben haben, mit dem Sie zufrieden waren, lohnt es sich vielleicht, mit anderen Methoden zu experimentieren, um den Text aufzulockern. Die authentische Stimme des Autors ist in einem Blogbeitrag über Code genauso wichtig wie in jedem anderen. Ihre Stimme wird durch eine gut geplante Strategie, die sich natürlich anfühlt, noch verstärkt.

Technische Begriffe

Natürlich ist es in Ordnung, darüber zu sprechen, wie man Witze macht und GIFs hinzufügt, um seinen Text aufzupeppen, aber irgendwann muss man in die trüben Gewässer der Akronyme und der ungarischen Schreibweise eintauchen.

Die erste Möglichkeit, mit Fachterminologie umzugehen, besteht darin, sich zu vergewissern, dass Sie Ihren Beitrag richtig eingeordnet haben. Ein Blogbeitrag, in dem Sie jeden Fachbegriff in mehreren Absätzen erklären müssen, sollte wahrscheinlich nicht derselbe sein, in dem Sie mehrere Fachbegriffe in einem Satz verwenden. Wenn Sie sich dabei ertappen, dass Sie viele Fachbegriffe vermischen und davon ausgehen, dass niemand sie alle kennt, können Sie den Begriff mit seiner kanonischen Definition verknüpfen, anstatt ihn zu sehr zu erklären. Sie können Ihren Beitrag auch in zwei Teile aufteilen, mit einer optionalen Vorgeschichte, die alle Grundlagen abdeckt, die einige Leute vielleicht überspringen möchten.

Um Ihren Text weniger trocken zu gestalten, sollten Sie Fachbegriffe in den Erzählfluss Ihres Beitrags einbauen. Anstatt also:

"getData ist der Name der Funktion, die die Daten abruft. Ihr Rückgabewert ist output. Sie kann nichts oder ein Objekt zurückgeben. Sie nimmt zwei Argumente entgegen. source ist das erste Argument, und filter ist das zweite, das optional ist."

So können Sie Fachbegriffe in die natürliche Sprache integrieren:

"Durch die Übergabe von Daten source in getData als erstes Argument übergeben, können wir ein output Objekt erhalten, das unsere Daten enthält. Optional können wir ein filter hinzufügen, um die zurückgegebenen Daten zu reduzieren. Wenn es keine Übereinstimmungen gibt, getData einfach zurück null."

Es mag verlockend sein, Fachausdrücke mit einer Art Formalität zu behandeln, aber ich denke, das macht den Text viel schwerer verdaulich. Die Art und Weise, wie Sie mit jemandem, mit dem Sie gemeinsam programmieren, über den Code sprechen würden, an dem Sie gemeinsam arbeiten, wird sofort klarer sein.

Die Rolle der Formatierung

Das Hin- und Herwechseln zwischen Erzähl- und Variablennamen, ohne dass Sie explizit darauf hinweisen, was Sie tun, wird ermöglicht durch <code> Tags in der endgültigen HTML-Datei Ihres Beitrags. Sie geben einen visuellen Hinweis darauf, dass Sie über ein bestimmtes Element der technischen Lösung sprechen, und sie können auch von unterstützenden Technologien erkannt werden. Jede andere Formatierung von Fachbegriffen, wie z. B. das Fettdrucken des Namens einer bestimmten Technologie oder eines Tools, bleibt Ihnen oder dem Style Guide Ihrer Organisation überlassen.

Die Art und Weise, wie Sie Codeblöcke formatieren, ist ebenfalls wichtig. Zumindest ist es hilfreich, die Syntax hervorzuheben. Das macht den Code nicht nur optisch leichter verständlich, sondern sorgt auch für visuelles Interesse in Ihrem Beitrag. Code in Codeblöcken sollte für Ihren Beitrag aufgeräumt werden. Wenn Ihre Code-Kommentare dieselben Dinge erklären wie Ihr Blogbeitrag, können Sie sie entfernen, um weniger Code zu präsentieren. Sie können auch alle vererbten Einrückungen des Codes entfernen, damit Sie nicht horizontal scrollen müssen, um ihn zu lesen.

Die Formatierung Ihres Beitrags in Unterabschnitten ist nützlich für die Organisation von Informationen und kann, je nach Blog-Plattform, die Sie verwenden, Navigationskürzel innerhalb des Beitrags bieten. Sie können auch Nebenbemerkungen und Aufzählungslisten verwenden, um den Beitrag zu gliedern. Übertreiben Sie es nur nicht mit der Formatierung. Die meisten Blog-Beiträge sollten immer noch hauptsächlich aus Text bestehen, auch wenn sie sich mit Code befassen.

Die Verlinkung zu anderen Ressourcen verdient eine kleine Strategie. Wenn Sie etwas Hilfreiches gefunden haben und es sich natürlich in den Fluss Ihres Textes einfügt, darauf zu verlinken, ist es nützlich, die zusätzlichen Informationen im Kontext zu haben. Sie sollten aber nicht so viele Links in Ihren Text einbauen, dass es ablenkt. Wenn Sie viele Links einfügen möchten, können Sie eine Liste am Anfang oder am Ende des Textes einfügen. Das hat auch den Vorteil, dass es die Leute nicht dazu verleitet, mitten im Text aufzuhören und woanders hinzugehen.

Bilder verwenden

Die Verwendung von Bildern ist in Nachrichtenartikeln und anderen Inhalten, die einen längeren Produktionsprozess durchlaufen als ein Blogbeitrag, ziemlich üblich. Auch bei technischen Artikeln ist es üblich, mindestens ein Hauptbild zu verwenden. Wir haben bereits über den Wert von Bildern gesprochen.

In technischen Blogbeiträgen können auch Bilder im Text verwendet werden. Dabei kann es sich um eine visuelle Auflockerung handeln, z. B. GIFs, die den Text auflockern, oder um Erklärungen. Die einzigen Überlegungen, die bei dekorativen Bildern angestellt werden müssen, sind rechtliche Fragen und Fragen der Zugänglichkeit. Mit der Erlaubnis, das Bild zu verwenden, und einer rücksichtsvollen Beschriftung sollten sie in Ordnung sein.

Einige technische Concepts können durch eine visuelle Demonstration veranschaulicht werden. Sie können die Schritte eines Einrichtungsvorgangs per Screenshot darstellen oder den Vorgang als GIF abbilden. Es kann auch hilfreich sein, Verzeichnisstrukturen, Beispielausgaben oder eine Benutzeroberfläche zu zeigen, die Sie im Beitrag nicht programmieren. Es ist jedoch wichtig, dass Sie sich bei diesen Dingen nicht ausschließlich auf Bilder verlassen. Sie sollten immer noch erklären, was auf dem Bild zu sehen ist, oder genügend Informationen geben, damit die Leute das Gleiche lokal erzeugen können.

Code erläutern

Wenn Sie einen Blogbeitrag über ein Stück Code schreiben, sollten Sie den Code erklären. Wenn Sie Ihre Leser auf ein Repo verweisen, ein paar Zeilen erzählen und Ihr Twitter-Handle fallen lassen, ist es unwahrscheinlich, dass ein sehr nützlicher Blogbeitrag entsteht.

Wenn der Code für Ihren Blog-Beitrag speziell für diesen Zweck geschrieben wird (und nicht Teil eines größeren Projekts ist), ist es sehr hilfreich, wenn Sie die Schritte, die Sie zur Erstellung des Beitrags unternehmen, während des Programmierens aufzeichnen. So erhalten Sie eine fertige Gliederung für den Beitrag. Sie können sich sogar wortwörtlich Notizen zu Ihren Schritten im Blogbeitrag machen, sobald der Code fertig ist, voilàist Ihre Gliederung bereits fertiggestellt. Wenn der Code nur ein Teil von etwas anderem ist, finden Sie heraus, welche Teile für den Inhalt Ihres Beitrags entscheidend sind, und ordnen Sie sie so an, dass die ersten Teile, die Sie besprechen, die Abhängigkeiten der folgenden Teile sind.

Das sind natürlich nur allgemeine Vorschläge. Wenn Sie den Code eines anderen analysieren oder etwas wirklich Komplexes erklären wollen, ist es vielleicht ganz gut, mit dem fertigen Produkt zu beginnen und einen "Wie haben sie das gemacht"-Ansatz zu wählen.

Ein Trick, der meiner Meinung nach gut funktioniert, besteht darin, den Text um den Code herum so zu schreiben, als gäbe es die Codebeispiele nicht. Man kann sich das auch so vorstellen, als ob man ein Interview mit einem Programmierer führen würde und die wichtigen Teile der Lösung ausdrücken müsste, während man die Implementierungsdetails unausgesprochen lässt. Die Leute suchen wahrscheinlich etwas in einem Blog-Post, das sie nicht bekommen können, wenn sie sich das GitHub-Repository ansehen, also sollte ein Blog-Post mehr tun, als nur zu sagen, "Jetzt fügen wir die getData Funktion:" Es gibt einen schmalen Grat zwischen dieser Aussage und der Wiederholung des gesamten Codeblocks in natürlicher Sprache.

Die Art und Weise, wie Sie Ihren Code aufteilen, kann dabei helfen, die richtige Balance zwischen Erklärung und Selbstdokumentation zu finden. Wenn es Ihnen gelingt, Ihren Code in Blöcke mit etwa zehn wichtigen Zeilen aufzuteilen (Dinge, die keine Standardtexte oder schließenden Klammern sind), können Sie einen Absatz mit 2-3 Sätzen schreiben, der jede Zeile erklärt, und dabei ein gutes Tempo einhalten. Aber das kann man nicht immer tun. Manche Funktionen sind riesig.

Wenn der Code, den Sie besprechen müssen, sehr lang ist, sollten Sie ihn künstlich aufspalten. Ich ziehe es vor, dies zu tun, indem ich Platzhalterkommentare hinterlasse wie //INSTANTIATE VARIABLES und //FETCH VALUESdamit ich nicht in letzter Minute den Code selbst ändern und möglicherweise einen Fehler einbauen muss. Es funktioniert aber auch, langen Code in Module oder separate Funktionen aufzuteilen. Durch das Hinzufügen von Abstraktionen wird Ihr Code viel einfacher zu diskutieren, und der gleiche Vorteil der Wiederverwendbarkeit, den Sie im Code selbst erhalten, kann auch in Ihren Blogbeiträgen zum Tragen kommen. Wenn Sie wieder über ein ähnliches Thema schreiben, können Sie diese Teile und vielleicht sogar ihre Erklärung wiederverwenden.

Einpacken

Am Ende Ihres Beitrags ist es sinnvoll, das erwartete Ergebnis zu bestätigen. Wenn Ihr Leser bei jedem Schritt mitcodiert hat und Fehler erhält, hat er wahrscheinlich schon den Verdacht, dass es sich um ein Missverständnis handelt. Aber das ist nicht immer der Fall. Sie könnten abschließend sagen: "Jetzt haben Sie Ihren Anwendungscode fertig. Sie müssen nur noch Ihre API-Anmeldedaten einrichten, indem Sie dieser Anleitung und schon können Sie die Anwendung ausführen."

Wenn Sie am Ende Ihres Beitrags angelangt sind und nicht mehr viel zu sagen haben, ist das ein gutes Zeichen dafür, dass Sie den Rahmen für den Beitrag richtig gesetzt haben. Wenn Sie viele Vorbehalte in zusätzliche Absätze packen, sollten Sie sich überlegen, ob Sie nicht die Dinge im Code oder im Beitrag korrigieren sollten, die Sie stören.

Der letzte Schritt beim Schreiben eines technischen Blogbeitrags ist derselbe wie bei einem nicht-technischen Beitrag: die Bearbeitung. Bei einem technischen Blogbeitrag ist es wichtig, dass Sie alle Vorschläge, die von einem automatischen Korrekturleseprogramm kommen, manuell überprüfen. Wenn Sie Änderungen an Ihren Codeblöcken vornehmen müssen, vergewissern Sie sich, dass der Code danach noch funktioniert.

Wenn Sie daran interessiert sind, einen technischen Blog-Beitrag über Ihre Arbeit mit den APIs von Vonage zu schreiben, nehmen wir derzeit Einsendungen für unser Entwickler-Spotlight Programm.