Technische Dokumentation für Entwickler

HTML, CSS, JavaScript, Python, PHP, C++, Dart – es gibt so viele Programmiersprachen und Sie beherrschen vielleicht sogar mehrere fließend! Aber während wir bestrebt sind, mehr und besseren Code zu schreiben, wird die Art und Weise, wie wir in alltäglicher Sprache schreiben und kommunizieren, immer wichtiger... und vielleicht sogar übersehen.

Die Art und Weise, wie wir über Code und um Code herum schreiben, ist wohl genauso wichtig wie der Code selbst. Und unabhängig davon, wo Sie sich auf dieser Linie befinden, sind wir uns alle einig, dass unsere Worte das Potenzial haben, die Effektivität von Code sowohl zu fördern als auch zu beeinträchtigen.

In diesem Artikel möchte ich skizzieren, wie diese beiden scheinbar unterschiedlichen Bereiche – Programmierung und Schreiben – zusammenkommen und unsere Entwicklerfähigkeiten auf die nächste Stufe heben können.

Warten, technische Dokumentation? Ja, genau das meine ich. Ich glaube wirklich, dass wir alle in irgendeiner Form Schreiber sind. Und ich bin hier, um Ihnen eine Einführung mit Schreibtipps, Ratschlägen und Beispielen zu geben, wie dies Sie sowohl zu einem besseren Entwickler als auch zu einem besseren Kommunikator machen kann.

Technische Dokumentation ist überall

Letztes Jahr hat das Team hinter dem beliebten Mac Git-Client Tower über 4.000 Entwickler befragt und festgestellt, dass fast 50% von ihnen zwischen 3-6 Stunden am Tag mit dem Schreiben von Code verbrachten.

Und ja, das ist eine Umfrage, die eine ziemlich kleine Gruppe befragt, aber ich stelle mir vor, dass viele von uns irgendwo in diesem Bereich liegen. Wie dem auch sei, ein Entwickler schreibt nicht rund um die Uhr Code, denn wie diese Umfrage nahelegt, verbringen wir viel Zeit mit anderen Dingen.

Das könnte beinhalten

• eine neue Funktion zu demonstrieren,
• diese neue Funktion zu dokumentieren,
• ein Arbeitsticket im Zusammenhang mit dieser neuen Funktion zu aktualisieren oder
• Arbeit zu backloggen, um diese neue Funktion zu unterstützen.

Natürlich gibt es auch immer Zeit für Toilettenpausen und Wordle.

Wie dem auch sei, die meisten Dinge, die wir typischerweise tun, beinhalten die Kommunikation mit Menschen wie Ihrem Team, Kollegen, Kunden, Benutzern und anderen Entwicklern.

Wir verbringen also einen guten Teil unserer Zeit mit der Kommunikation mit Menschen durch Worte zusätzlich zur Kommunikation, die wir mit Computern durch Code haben. Worte sind geschriebene Sprache. Und wenn wir unsere Worte besser schreiben würden, würden wir besser kommunizieren. Wenn wir besser kommunizieren, ist es wahrscheinlicher, dass wir das bekommen, was wir wollen.

Das ist Technische Dokumentation 101.

Und das hört hier nicht einmal auf. Manche Programmierer machen auch gerne eigene Produkte, was bedeutet, dass sie Marketing zu ihrer Aufgabe machen müssen. Technische Dokumentation spielt auch dabei eine große Rolle. Also ja. Ich denke, es ist ziemlich fair zu sagen, dass technische Dokumentation in der Tat überall ist.

Was ist eine gute Grammatik?

Bei so vielen Programmiersprachen da draußen ist das Letzte, was wir wollen, eine weitere zu lernen.

Grammatik ist ein integraler Bestandteil des Englischen und schöpft das volle Potenzial der Kommunikation aus. Sie macht uns formeller, professioneller und zusammenhängender.

Lassen Sie mich Ihnen einen kurzen Überblick über Sprache geben.

Die englische Syntax

Genau wie Programmiersprachen hat Englisch eine klar definierte Syntax, und das beginnt mit Wörtern.

Wörter sind die Bausteine des Englischen und fallen in acht Kategorien

Stellen Sie sich diese wie UI-Komponenten vor: Sie sind modulare Teile, die Sie verschieben können, um einen vollständigen und robusten Satz zu konstruieren, genauso wie Sie eine vollständige und robuste UI zusammenfügen könnten. Müssen alle Komponenten jederzeit vorhanden sein? Sicherlich nicht! Stellen Sie einen Satz mit den Teilen zusammen, die Sie benötigen, um das Erlebnis zu vervollständigen, genau wie bei einer Benutzeroberfläche.

Stimme und Ton

Wortschatz, Zeichensetzung, Satzstruktur und Wortwahl. Das sind alles Zutaten des Englischen. Wir verwenden sie, um Ideen auszutauschen, mit unseren Freunden und Familien zu kommunizieren und E-Mails an unsere Kollegen zu senden.

Aber es ist entscheidend, auf den Klang unserer Nachrichten zu achten. Es ist erstaunlich, wie ein Ausrufezeichen den Ton einer Nachricht völlig verändern kann

1. Ich mag Programmierung.
2. Ich mag Programmierung! :)

Es ist leicht, Stimme mit Ton zu verwechseln und umgekehrt.

Stimme bezieht sich auf unsere Wortwahl, die vom Kontext abhängt. Zum Beispiel wird ein Tutorial für Anfänger wahrscheinlich Slang und informelle Sprache verwenden, um eine freundliche Stimme zu vermitteln, während Dokumentationen in einem formellen, ernsten und professionellen Stil verfasst sein können, um direkt auf den Punkt zu kommen.

Die gleiche Nachricht, in zwei verschiedenen Stimmen geschrieben

• Lustig: „Erweitern Sie Ihr soziales Netzwerk und bleiben Sie über die neuesten Trends auf dem Laufenden.“
• Ernster: „Finden Sie Jobs auf einer der größten Social-Networking-Apps und Online-Jobbörsen.“

Es ist nicht ungewöhnlich, versehentlich Nachrichten zu schreiben, die als herablassend, beleidigend und unprofessionell empfunden werden. Hier kommt Ton ins Spiel. Lesen Sie Ihre Nachrichten laut vor, lassen Sie andere sie für sich lesen und experimentieren Sie mit Ihrer Zeichensetzung und Satzstruktur. So schärfen Sie Ihren Ton.

Hier ist eine andere Denkweise: Ihre Stimme ändert sich nie, aber Ihr Ton schon. Ihre Stimme ist vergleichbar mit dem, wer Sie als Person sind, während der Ton angibt, wie Sie in einer bestimmten Situation reagieren.

Aktiv- und Passivform

Ein Satz enthält immer ein Subjekt, ein Verb und ein Objekt. Die Reihenfolge, in der diese erscheinen, bestimmt, ob der Satz in der Aktiv- oder Passivform geschrieben ist.

Das Subjekt kommt zuerst in einer Aktivform. Zum Beispiel: „CSS malt den Hintergrund.“

Sätze, die eine Aktivform verwenden, sind direkter als ihre Gegenstücke. Sie sind klarer, kürzer und verständlicher – perfekt für eine professionellere Stimme, die direkt auf den Punkt kommt.

Bei einer Passivform kommt das Subjekt zuletzt. (Sehen Sie, was ich dort getan habe?) Das bedeutet, dass unser Subjekt – in diesem Fall CSS – am Ende steht, so: „Der Hintergrund wird von CSS gemalt.“

Leser wandeln eine Passivform normalerweise in ihrem Kopf in eine Aktivform um, was zu mehr Verarbeitungszeit führt. Wenn Sie jemals gehört haben, dass das Schreiben in Aktivform besser ist, ist dies normalerweise der Grund dafür. Technische Autoren bevorzugen meistens die Aktivform, mit sehr wenigen Ausnahmen wie der Zitierung von Forschung: „Es wurde vorgeschlagen, dass …“

Aber das bedeutet nicht, dass Sie immer nach einer Aktivform streben sollten. Der Wechsel von einer zur anderen – selbst im selben Absatz – kann Ihren Inhalt nahtloser von einem Satz zum nächsten fließen lassen, wenn er effektiv eingesetzt wird.

Fehler vermeiden

Grammatik dreht sich um Struktur und Korrektheit der Sprache, und nichts ist besser, um das zu erreichen, als ein schnelles Korrekturlesen Ihres Dokuments. Es ist sehr wichtig, Ihre Texte von Rechtschreibfehlern, Grammatikproblemen und semantischen Mängeln zu befreien.

Am Ende dieses Artikels zeige ich Ihnen die unschätzbaren Werkzeuge, die Profis verwenden, um Schreibfehler zu vermeiden. Offensichtlich gibt es heutzutage in fast allem integrierte Rechtschreibprüfungen; unsere Code-Editoren haben sogar Rechtschreibprüfungs- und Linting-Plugins, um Fehler zu verhindern. 

Aber wenn Sie nach einem Ein-Stopp-Werkzeug für alle Grammatik-Themen suchen, ist Grammarly eines der am weitesten verbreiteten Werkzeuge. Ich erhalte dafür keine Provision oder so etwas. Es ist einfach ein wirklich tolles Werkzeug, das viele Redakteure und Autoren verwenden, um saubere und klare Inhalte zu schreiben – ähnlich wie Sie Emmet, eslint oder einen anderen Linter verwenden würden, um sauberen und klaren Code zu schreiben.

Schreiben von Code-Kommentaren

Die Dinge, die wir für andere Entwickler schreiben, können große Auswirkungen auf die Gesamtqualität unserer Arbeit haben, sei es das, was wir im Code schreiben, wie wir den Code erklären oder wie wir Feedback zu einem Codeabschnitt geben.

Es ist interessant, dass jede Programmiersprache über eine Standardfunktion zum Schreiben eines Kommentars verfügt. Sie sollten erklären, was der Code tut. Damit meine ich nicht vage Kommentare wie diesen

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

Verwenden Sie stattdessen Kommentare, die mehr Informationen liefern

red *= 1.2 // Apply a 'reddish' effect to the image

Es geht um den Kontext. „Welche Art von Programm baue ich?“ ist genau die Art von Frage, die Sie sich stellen sollten.

Kommentare sollten Mehrwert bieten

Bevor wir uns ansehen, was einen „guten“ Code-Kommentar ausmacht, hier sind zwei Beispiele für faule Kommentare

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

Denken Sie daran, dass der Zweck eines Kommentars darin besteht, einem Codeabschnitt Mehrwert zu verleihen, nicht ihn zu wiederholen. Wenn Sie das nicht tun können, ist es besser, den Code so zu belassen, wie er ist. Was diese Beispiele „faul“ macht, ist, dass sie nur wiederholen, was der Code offensichtlich tut. In diesem Fall sind die Kommentare redundant, da sie uns sagen, was wir bereits wissen – sie fügen keinen Wert hinzu!

Kommentare sollten den aktuellen Code widerspiegeln

Veraltete Kommentare sind in großen Projekten keine Seltenheit; ich wage zu sagen, in den meisten Projekten.

Stellen wir uns David vor, einen Programmierer und einen coolen Kerl, mit dem man abhängen kann. David möchte eine Liste von Zeichenfolgen alphabetisch von A bis Z sortieren, also tut er das Offensichtliche in JavaScript

cities = sortWords(cities) // sort cities from A to Z

David stellt dann fest, dass sortWords() eigentlich Listen von Z nach A sortiert. Das ist kein Problem, da er die Ausgabe einfach umkehren kann

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

Leider hat David seinen Kommentar nicht aktualisiert.

Stellen Sie sich nun vor, ich hätte Ihnen diese Geschichte nicht erzählt und alles, was Sie sahen, war der obige Code. Sie würden natürlich denken, dass nach dem Ausführen der zweiten Codezeile `cities` von Z nach A sortiert wäre! Dieses ganze Verwirrungsfiasko wurde durch einen veralteten Kommentar verursacht.

Auch wenn dies ein übertriebenes Beispiel sein mag, kann etwas Ähnliches passieren (und passiert oft), wenn Sie gegen eine knappe Frist arbeiten. Glücklicherweise kann dies verhindert werden, indem eine einfache Regel befolgt wird… ändern Sie Ihre Kommentare zur gleichen Zeit, in der Sie den Code ändern.

Das ist eine einfache Regel, die Ihnen und Ihrem Team viel technische Schuld ersparen wird.

Nachdem wir nun wissen, wie schlecht geschriebene Kommentare aussehen, schauen wir uns einige gute Beispiele an.

Kommentare sollten idiomatischen Code erklären

Manchmal ist der natürliche Weg, Dinge zu tun, nicht der richtige. Programmierer müssen möglicherweise die Standards ein wenig „brechen“, aber wenn sie es tun, ist es ratsam, einen kleinen Kommentar zu hinterlassen, der ihre Begründung erklärt

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

Das ist hilfreich, oder? Wenn Sie für die Überprüfung dieses Codes verantwortlich gewesen wären, wären Sie vielleicht versucht gewesen, ihn zu korrigieren, ohne dass der Kommentar erklärt hätte, was vor sich geht.

Kommentare können zukünftige Aufgaben identifizieren

Eine weitere nützliche Sache bei Kommentaren ist, zuzugeben, dass es noch mehr zu tun gibt.

// TODO: use a more efficient algorithm
linearSort(ids)

Auf diese Weise können Sie sich auf Ihren Fluss konzentrieren. Und zu einem späteren Zeitpunkt können Sie oder jemand anderes zurückkommen und es beheben.

Kommentare können zurück zum Ursprung verlinken

Sie haben also gerade eine Lösung für Ihr Problem auf StackOverflow gefunden. Nachdem Sie diesen Code kopiert und eingefügt haben, ist es manchmal gut, einen Link zu der Antwort zu behalten, die Ihnen geholfen hat, damit Sie später darauf zurückgreifen können.

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

Dies ist wichtig, da sich Lösungen ändern können. Es ist immer gut zu wissen, woher Ihr Code stammt, falls er jemals kaputt geht.

Schreiben von Pull Requests

Pull Requests (PRs) sind ein grundlegender Aspekt jedes Projekts. Sie stehen im Mittelpunkt von Code-Reviews. Und Code-Reviews können schnell zu einem Engpass für die Leistung Ihres Teams werden, wenn die Formulierungen nicht gut sind.

Eine gute PR-Beschreibung fasst zusammen, was geändert wird und warum es geändert wird. Große Projekte haben eine Pull Request-Vorlage, wie diese, angepasst von einem echten Beispiel

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

Vermeiden Sie vage PR-Titel

Bitte vermeiden Sie Titel, die so aussehen

• Build reparieren.
• Fehler beheben.
• Patch hinzufügen.

Diese versuchen nicht einmal, zu beschreiben, welchen Build, Fehler oder Patch wir gerade behandeln. Ein wenig zusätzliche Details darüber, welcher Teil des Builds repariert wurde, welcher Fehler behoben wurde oder welcher Patch hinzugefügt wurde, können viel dazu beitragen, eine bessere Kommunikation und Zusammenarbeit mit Ihren Kollegen zu etablieren. Es nivelliert und bringt alle auf den gleichen Stand.

PR-Titel werden traditionell im imperativen Tempus geschrieben. Sie sind eine Ein-Zeilen-Zusammenfassung des gesamten PR und sollten beschreiben, was vom PR getan wird.

Hier sind einige gute Beispiele

• Unterstützung für benutzerdefinierte srcset-Attribute in NgOptimizedImage
• Standardmäßige Bildkonfiguration auf 75% Bildqualität
• Explizite Selektoren für alle integrierten ControlValueAccessors hinzufügen

Lange PRs vermeiden

Ein großer PR bedeutet eine riesige Beschreibung, und niemand möchte Hunderte oder Tausende von Codezeilen überprüfen, manchmal nur, um das Ganze am Ende abzulehnen!

Stattdessen könnten Sie

• mit Ihrem Team über Issues kommunizieren,
• einen Plan erstellen,
• das Problem in kleinere Teile zerlegen oder
• an jedem Teil separat mit seinem eigenen PR arbeiten.

Ist das nicht viel sauberer jetzt?

Details im PR-Body angeben

Im Gegensatz zum PR-Titel ist der Body der Ort für alle Details, einschließlich

• Warum wird der PR durchgeführt?
• Warum ist das der beste Ansatz?
• Etwaige Mängel des Ansatzes und Ideen zur Behebung, falls möglich
• Die Fehler- oder Ticketnummer, Benchmark-Ergebnisse usw.

Fehler melden

Fehlermeldungen sind einer der wichtigsten Aspekte jedes Projekts. Und alle großartigen Projekte basieren auf Nutzerfeedback. Normalerweise finden die Benutzer, selbst nach unzähligen Tests, die meisten Fehler. Benutzer sind auch große Idealisten und haben manchmal Funktionsideen; hören Sie ihnen bitte zu!

Für technische Projekte wird all dieser Kram durch das Melden von Problemen erledigt. Eine gut geschriebene Issue ist für einen anderen Entwickler leicht zu finden und darauf zu reagieren.

Zum Beispiel kommen die meisten großen Projekte mit einer Vorlage

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

Screenshots sammeln

Erfassen Sie das Problem mit dem Screenshot-Tool Ihres Systems.

Wenn es sich um einen Screenshot eines CLI-Programms handelt, stellen Sie sicher, dass der Text klar ist. Wenn es sich um ein UI-Programm handelt, stellen Sie sicher, dass der Screenshot die richtigen Elemente und Zustände erfasst.

Möglicherweise müssen Sie eine tatsächliche Interaktion erfassen, um das Problem zu demonstrieren. Wenn dies der Fall ist, versuchen Sie, GIFs mit einem Bildschirmaufzeichnungswerkzeug aufzunehmen.

So reproduzieren Sie das Problem

Für Programmierer ist es viel einfacher, einen Fehler zu beheben, wenn er auf ihrem Computer live ist. Deshalb sollte eine gute Commit-Nachricht die Schritte zur genauen Reproduktion des Problems enthalten.

Hier ist ein Beispiel:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

Schlagen Sie eine Ursache vor

Sie sind derjenige, der den Fehler gefunden hat, also können Sie vielleicht einige mögliche Ursachen vorschlagen, warum er da ist. Vielleicht tritt der Fehler nur auf, nachdem Sie ein bestimmtes Ereignis erlebt haben, oder vielleicht tritt er nur auf Mobilgeräten auf.

Es schadet auch nicht, den Code zu durchsuchen und vielleicht die Ursache des Problems zu identifizieren. Dann wird Ihr Issue viel schneller geschlossen und Sie werden wahrscheinlich dem zugehörigen PR zugeordnet.

Kommunikation mit Kunden

Sie arbeiten vielleicht als freiberuflicher Einzelunternehmer oder sind vielleicht der leitende Entwickler eines kleinen Teams. In beiden Fällen nehmen wir an, dass Sie für die Schnittstelle zu den Kunden eines Projekts zuständig sind. 

Nun, das Klischee des Programmierers ist, dass wir schlecht kommunizieren. Wir sind bekannt dafür, zu viel Fachjargon zu verwenden, anderen zu sagen, was möglich ist und was nicht, und sogar defensiv zu werden, wenn jemand unseren Ansatz in Frage stellt.

Wie können wir dieses Klischee mildern? Fragen Sie die Kunden, was sie wollen, und hören Sie immer auf ihr Feedback. Hier erfahren Sie, wie Sie das tun können.

Stellen Sie die richtigen Fragen

Stellen Sie zunächst sicher, dass Sie und der Kunde auf derselben Wellenlänge sind

• Wer ist Ihre Zielgruppe?
• Was ist das Ziel der Website?
• Wer ist Ihr engster Wettbewerber und was machen sie richtig?

Fragen zu stellen ist auch eine gute Möglichkeit, positiv zu schreiben, insbesondere in Situationen, in denen Sie mit dem Feedback oder der Entscheidung eines Kunden nicht einverstanden sind. Fragen zu stellen zwingt die Person, ihre eigenen Behauptungen zu unterstützen, anstatt dass Sie sie angreifen, indem Sie Ihre eigene Position verteidigen.

• Sind Sie damit einverstanden, auch wenn dies mit zusätzlichen Leistungskosten verbunden ist?
• Hilft uns die Verschiebung der Komponente, unser Ziel besser zu erreichen?
• Großartig, wer ist für die Wartung danach verantwortlich? 
• Wissen Sie aus dem Stegreif, ob der Kontrast zwischen diesen beiden Farben die WCAG AA-Standards erfüllt?

Fragen sind viel unschuldiger und fördern Neugier statt Feindseligkeit.

Verkaufen Sie sich

Wenn Sie ein Angebot für einen potenziellen Kunden machen, müssen Sie ihn davon überzeugen, Sie einzustellen. Warum sollte der Kunde Sie wählen? Es ist wichtig, Folgendes anzugeben:

• Wer Sie sind
• Was Sie tun
• Warum Sie gut für den Job geeignet sind
• Links zu relevanter Arbeit, die Sie geleistet haben

Und wenn Sie den Job bekommen und einen Vertrag aufsetzen müssen, denken Sie daran, dass es keinen einschüchternderen Inhalt gibt als eine Menge Juristensprache. Obwohl er für Designprojekte geschrieben wurde, kann der Contract Killer ein guter Ausgangspunkt sein, um etwas viel Freundlicheres zu schreiben.

Ihre Liebe zum Detail könnte den Unterschied zwischen Ihnen und einem anderen Entwickler ausmachen, der versucht, dasselbe Projekt zu gewinnen. Meiner Erfahrung nach stellen Kunden genauso leicht einen Entwickler ein, mit dem sie ihrer Meinung nach Spaß haben werden, wie denjenigen, der technisch am kompetentesten oder erfahrensten für die Stelle ist.

Schreiben von Mikrokopien

Mikrokopie ist die Kunst, benutzerfreundliche UI-Nachrichten zu schreiben, z. B. Fehlermeldungen. Ich wette, es gab Zeiten, in denen Sie als Entwickler Fehlermeldungen schreiben mussten, weil sie bis zur Veröffentlichung auf Eis gelegt wurden.

Das mag der Grund sein, warum wir manchmal Fehler wie diese sehen

Error: Unexpected input (Code 693)

Fehler sind das Letzte, womit Ihre Benutzer zu tun haben wollen. Aber sie passieren, und wir können nichts dagegen tun. Hier sind einige Tipps, um Ihre Mikrokopie-Fähigkeiten zu verbessern.

Vermeiden Sie Fachjargon

Die meisten Leute wissen nicht, was ein Server ist, während 100 % der Programmierer das tun. Deshalb ist es nicht ungewöhnlich, in einer Fehlermeldung ungewöhnliche Begriffe zu sehen, wie z. B. API oder „Timeout Execution“.

Wenn Sie sich nicht mit einem technischen Kunden oder einer technischen Benutzerbasis befassen, haben die meisten Ihrer Benutzer wahrscheinlich keinen Informatikkurs besucht und wissen nicht, wie das Internet funktioniert und warum etwas Bestimmtes nicht funktioniert. Daher der Fehler.

Daher sollte eine gute Fehlermeldung nicht erklären, *warum* etwas schief gelaufen ist, denn solche Erklärungen könnten die Verwendung beängstigender technischer Begriffe erfordern. Deshalb ist es sehr wichtig, Fachjargon zu vermeiden.

Schieben Sie niemals dem Benutzer die Schuld zu

Stellen Sie sich Folgendes vor: Ich versuche, mich bei Ihrer Plattform anzumelden. Also öffne ich meinen Browser, besuche Ihre Website und gebe meine Daten ein. Dann wird mir gesagt: „Ihre E-Mail/Ihr Passwort ist falsch.“

Auch wenn diese Nachricht dramatisch als feindselig erscheint, fühle ich mich unbewusst dumm. Mikrokopie besagt, dass es niemals in Ordnung ist, dem Benutzer die Schuld zuzuweisen. Versuchen Sie, Ihre Nachricht in etwas weniger aufzeigendes zu ändern, wie in diesem Beispiel, das von Mailchimps Login übernommen wurde: „Entschuldigung, diese E-Mail-Passwort-Kombination ist nicht korrekt. Wir können Ihnen helfen, Ihr Konto wiederherzustellen.“

Ich möchte auch die Wichtigkeit hinzufügen, ALLES GROSSGESCHRIEBEN und Ausrufezeichen zu vermeiden! Sicher, sie können verwendet werden, um Begeisterung zu vermitteln, aber in der Mikrokopie erzeugen sie ein Gefühl der Feindseligkeit gegenüber dem Benutzer.

Überfordern Sie den Benutzer nicht

Humor in Ihrer Mikrokopie zu verwenden, ist eine gute Idee! Es kann die Stimmung auflockern und ist ein einfacher Weg, die Negativität zu mildern, die selbst von den schlimmsten Fehlern verursacht wird.

Aber wenn Sie ihn nicht *perfekt* verwenden, kann er als herablassend und beleidigend für den Benutzer empfunden werden. Das ist ein *großes* Risiko.

Mailchimp sagt es gut

[Ü]bertreiben Sie es nicht mit Witzen – erzwungener Humor kann schlimmer sein als gar keiner. **Wenn Sie unsicher sind, bleiben Sie ernst.**

(Hervorhebung von mir)

Schreiben von zugänglichem Markup

Wir könnten leicht einen ganzen Artikel über Barrierefreiheit und deren Zusammenhang mit technischem Schreiben verbringen. Selbst, Barrierefreiheit ist oft in Content-Styleguides enthalten, auch in denen für Microsoft und Mailchimp.

Sie sind Entwickler und wissen wahrscheinlich bereits viel über Barrierefreiheit. Sie sind vielleicht sogar einer der sorgfältigeren Entwickler, die Barrierefreiheit zu einem Kernbestandteil ihres Arbeitsablaufs machen. Dennoch ist es unglaublich, wie oft Barrierefreiheitsaspekte in den Hintergrund gedrängt werden, egal wie wichtig es uns allen ist, zugängliche Online-Erlebnisse zu schaffen, die für alle Fähigkeiten inklusiv sind.

Wenn Sie also die Kopie eines anderen in Ihren Code implementieren, Dokumentation für andere Entwickler schreiben oder sogar selbst UI-Kopien schreiben, beachten Sie einige grundlegende bewährte Praktiken für Barrierefreiheit, da diese alle anderen Ratschläge für technisches Schreiben abrunden.

Dinge wie

• Verwendung von semantischen Tags, wo möglich (z. B. <nav>, <header>, <article>, usw.)
• Folgen einer logischen Überschriftenstruktur
• Hinzufügen von Alt-Text zu Bildern
• Achten Sie auf Inline-Semantik (Mandy Michael hat einen außergewöhnlichen Artikel dazu)

Andy Bell bietet einige relativ kleine Dinge, die Sie tun können, um Inhalte zugänglicher zu machen, und es lohnt sich, sie sich anzusehen. Und zum Spaß zeigt John Rhea einige nette Bearbeitungstricks, die möglich sind, wenn wir mit semantischen HTML-Elementen arbeiten.

Fazit

Das waren sechs Wege, die zeigen, wie technisches Schreiben und Entwicklung zusammenhängen. Während die Beispiele und Ratschläge vielleicht keine Raketenwissenschaft sind, hoffe ich, dass Sie sie nützlich fanden, sei es bei der Zusammenarbeit mit anderen Entwicklern, bei der Wartung Ihrer eigenen Arbeit, beim Schreiben eigener Texte in der Not oder sogar beim Entwurf eines Projektvorschlags.

Die Quintessenz: Das Schärfen Ihrer Schreibfähigkeiten und das Bemühen, ein wenig mehr in Ihr Schreiben zu stecken, können Sie tatsächlich zu einem besseren Entwickler machen.

Ressourcen für technisches Schreiben

Wenn Sie sich für technisches Schreiben interessieren

• Ratschläge für technisches Schreiben (Chris Coyier)
• Googles Leitfaden für technisches Schreiben
• Grundlagen des technischen Schreibens (GitLab)
• UX Writing: Study Guide (Nielson Norman Group)
• Write the Docs (Community für technisches Schreiben)

Wenn Sie sich für Copywriting interessieren

• Copywriting 101 (Copyblogger)
• Was ist Copywriting? (Ionos)
• Guide zu SEO-Copywriting (Semrush)
• Copywriting ist immer noch Schreiben (The Guardian)

Wenn Sie sich für Mikrokopien interessieren

• Einführung in Mikrokopien (UX Planet)
• Apple's Human Interface Guidelines
• Microsoft's Writing Style Guide
• Mailchimp Content Style Guide

Wenn Sie sich für die Verwendung eines professionellen Styleguides zur Verbesserung Ihres Schreibens interessieren

• MLA Writing Style Guide
• AP Writing Style Guide
• APA Writing Style Guide
• Chicago Writing Style Guide

Wenn Sie sich für das Schreiben für Barrierefreiheit interessieren

• Verbessern Sie die Lesbarkeit des Inhalts auf Ihrer Website (Andy Bell)
• 15 Praktiken zur Verbesserung der Website-Zugänglichkeit (Bruce Lawson)
• Tools zum Testen der Barrierefreiheit (Chris Coyier)
• Warum nehmen Entwickler Barrierefreiheit nicht ernst? (Melanie Sumner)
• Benennung von Dingen zur Verbesserung der Barrierefreiheit (Hidde de Vries)