Technisches Schreiben für Entwickler

HTML, CSS, JavaScript, Python, PHP, C++, Dart – es gibt so viele Programmiersprachen da draußen und vielleicht beherrschen Sie sogar mehrere davon fließend! Aber da wir uns bemühen, mehr und besseren Code zu schreiben, wird die Art und Weise, wie wir in der Alltagssprache schreiben und kommunizieren, immer wichtiger … und vielleicht sogar übersehen.

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

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

Warten Sie, technische Redaktion? Ja, genau das meine ich. Ich bin fest davon überzeugt, dass wir alle auf die eine oder andere Weise Schriftsteller sind. Und ich bin hier, um Ihnen eine Einführung mit Schreibtipps, Ratschlägen und Beispielen zu geben, wie Sie dadurch zu einem besseren Entwickler und Kommunikator werden können.

Technisches Schreiben ist überall

Letztes Jahr hat das Team hinter dem beliebten Mac-Git-Client Tower, befragte mehr als 4,000 Entwickler und fanden heraus, dass fast 50 % von ihnen zwischen 3 und 6 Stunden am Tag damit verbrachten, Code zu schreiben.

Und ja, das ist eine Umfrage, die eine hübsche Nischengruppe befragt, aber ich kann mir vorstellen, dass viele von uns irgendwo in diesen Bereich fallen. Wie auch immer, ein Entwickler schreibt nicht rund um die Uhr Code, denn wie diese Umfrage zeigt, verbringen wir viel Zeit mit anderen Dingen.

Das könnte beinhalten:

• Demonstrieren einer neuen Funktion,
• Dokumentieren dieser neuen Funktion,
• Aktualisieren eines Arbeitstickets, das sich auf diese neue Funktion bezieht, oder
• Arbeitsrückstand zur Unterstützung dieser neuen Funktion.

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

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

Wir verbringen also einen guten Teil unserer Zeit damit, mit Menschen zu kommunizieren Worte zusätzlich zu der Kommunikation, die wir mit Computern haben Code. Wörter sind geschriebene Sprache. Und wenn wir unsere Worte besser schreiben würden, würden wir besser kommunizieren. Wenn wir besser kommunizieren, bekommen wir eher das, was wir wollen.

Das ist Technisches Schreiben 101.

Und das hört hier noch nicht einmal auf. Einige Programmierer stellen auch gerne ihre eigenen Produkte her, was bedeutet, dass sie das Marketing zu einem Teil ihrer Arbeit machen müssen. Auch die Technische Redaktion spielt dabei eine große Rolle. Also, ja. Ich denke, es ist ziemlich fair zu sagen, dass das Technische Schreiben ist in der Tat überall.

Was ist 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 erschließt das volle Potenzial der Kommunikation. Es macht uns formeller, professioneller und kohärenter.

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

Die englische Syntax

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

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

Denken Sie an diese wie UI Komponenten: Sie sind modulare Teile, die Sie verschieben können, um einen vollständigen und robusten Satz zu konstruieren, genauso wie Sie einen vollständigen und robusten Satz zusammensetzen könnten UI. Müssen alle Komponenten immer vorhanden sein? Sicherlich nicht! Setzen 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, Satzbau und Wortwahl. Dies sind alle Zutaten des Englischen. Wir verwenden sie, um Ideen auszutauschen, mit unseren Freunden und unserer Familie zu kommunizieren und E-Mails an unsere Kollegen zu senden.

Aber es ist entscheidend, die zu berücksichtigen klingen unserer Botschaften. Es ist erstaunlich, wie ein Ausrufezeichen den Ton einer Nachricht komplett verändern kann:

1. Ich mag Programmieren.
2. I Gefällt mir Programmierung! :)

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

Stimme betrifft unsere Wortwahl, die kontextabhängig ist. Zum Beispiel verwendet ein Tutorial für Anfänger eher Slang und informelle Sprache, um eine freundliche Stimme zu vermitteln, während die Dokumentation möglicherweise formal, ernsthaft und professionell geschrieben ist, um direkt auf den Punkt zu kommen.

Dieselbe Botschaft, geschrieben in zwei verschiedenen Stimmen:

• Fun: „Erweitern Sie Ihr soziales Netzwerk und bleiben Sie über aktuelle Trends auf dem Laufenden.“
• Ernst: „Finden Sie Jobs auf einem der größten Social-Networking-Apps und Online-Stellenmarkt.“

Es ist nicht ungewöhnlich, versehentlich Nachrichten zu schreiben, die herablassend, beleidigend und unprofessionell wirken. Das ist wo Ton ins Spiel kommt. Lesen Sie Ihre Nachrichten laut vor, lassen Sie sie von anderen vorlesen und experimentieren Sie mit Ihrer Interpunktion und Satzstruktur. So verfeinerst du deinen Ton.

So kann man es sich anders vorstellen: Ihre Stimme ändert sich nie, aber Ihr Tonfall schon. Ihre Stimme entspricht Ihrer Person, während Ihr Tonfall Ihre Reaktion in einer bestimmten Situation ist.

Aktive und passive Stimme

Ein Satz enthält immer einen Akteur, ein Verb und ein Ziel. Die Reihenfolge, in der diese kommen, bestimmt, ob der Satz im Aktiv oder Passiv geschrieben ist.

Der Schauspieler steht an erster Stelle Aktive Stimme. Zum Beispiel: „CSS malt den Hintergrund.“

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

Mit einem passive Stimme, der Schauspieler kommt zuletzt. (Siehst du, was ich da gemacht habe?) Das heißt, unser Akteur – in diesem Fall CSS – kommt am Ende so: „Der Hintergrund wird von CSS gemalt.“

Leser wandeln in der Regel ein Passiv in ihrem Kopf in ein Aktiv um, was zu einer längeren Verarbeitungszeit führt. Wenn Sie jemals gehört haben, dass das Schreiben mit aktiver Stimme besser ist, ist dies normalerweise der Grund dafür. Technische Redakteure bevorzugen die meiste Zeit das Aktiv, mit sehr wenigen Ausnahmen, wie z. B. das Zitieren von Forschungsergebnissen: „Es wurde vorgeschlagen, dass …“

Aber das bedeutet nicht, dass Sie immer nach einer aktiven Stimme streben sollten. Der Wechsel von einem zum anderen – sogar im selben Absatz – kann dazu führen, dass Ihre Inhalte nahtloser von einem Satz zum anderen fließen, wenn sie effektiv eingesetzt werden.

Fehler vermeiden

Bei der Grammatik dreht sich alles um die Struktur und Korrektheit der Sprache, und es gibt nichts Besseres, um dies zu erreichen, als ein schnelles Korrekturlesen Ihres Dokuments. Es ist sehr wichtig, Ihre Texte von Rechtschreibfehlern, Grammatikproblemen und semantischen Unvollkommenheiten 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 eingebaute Rechtschreibprüfungen; Unsere Code-Editoren verfügen sogar über Plugins zur Rechtschreibprüfung und Linting, um Fehler zu vermeiden. 

Aber wenn Sie nach einem One-Stop-Tool für alles rund um die Grammatik suchen, Grammarly ist eines der am weitesten verbreiteten Tools. Dafür bekomme ich kein Kickback oder so. Es ist einfach ein wirklich großartiges Tool, das viele Redakteure und Autoren verwenden, um saubere und klare Inhalte zu schreiben – ähnlich wie Sie Emmet, eslint oder einen anderen Linter verwenden, um sauberen und klaren Code zu schreiben.

Codekommentare schreiben

Die Dinge, die wir für andere Entwickler schreiben, können einen großen Einfluss auf die Gesamtqualität unserer Arbeit haben, sei es, was wir in den Code schreiben, wie wir den Code erklären oder wie wir Feedback zu einem Stück Code geben.

Es ist interessant, dass jede Programmiersprache mit einem Standardsatz von Funktionen ausgestattet ist, um einen Kommentar zu schreiben. Sie sollten erklären, was der Code tut. Damit meine ich nicht vage Kommentare wie diese:

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

Verwenden Sie stattdessen Kommentare, die weitere Informationen enthalten:

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

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

Kommentare sollten einen Mehrwert bieten

Bevor wir uns ansehen, was einen „guten“ Codekommentar ausmacht, sind hier 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, einen Codeabschnitt aufzuwerten, und nicht, ihn zu wiederholen. Wenn Sie das nicht tun können, sollten Sie den Code einfach so lassen, wie er ist. Was diese Beispiele „faul“ macht, ist, dass sie lediglich wiederholen, was der Code offensichtlich tut. In diesem Fall sind die Kommentare überflüssig, weil sie uns sagen, was wir bereits wissen – sie bringen keinen Mehrwert!

Kommentare sollten den aktuellen Code widerspiegeln

Veraltete Kommentare sind in großen Projekten keine Seltenheit; wage ich zu sagen, in vor allem warme Projekte.

Stellen wir uns David vor, einen Programmierer und einen rundum coolen Typen zum Abhängen. David möchte eine Liste von Strings alphabetisch von A bis Z sortieren, also macht er das Offensichtliche in JavaScript:

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

David erkennt dann, dass sortWords() tatsächlich 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 Codekommentar nicht aktualisiert.

Stellen Sie sich jetzt vor, ich hätte Ihnen diese Geschichte nicht erzählt, und alles, was Sie gesehen haben, war der obige Code. Sie würden natürlich denken, dass nach dem Ausführen dieser zweiten Codezeile "Städte" von Z bis A sortiert wären! Dieses ganze Verwirrungsfiasko wurde durch einen veralteten Kommentar verursacht.

Auch wenn dies ein übertriebenes Beispiel sein mag, kann (und passiert oft) etwas Ähnliches passieren, wenn Sie gegen eine knappe Frist antreten. Glücklicherweise kann dies verhindert werden, indem man eine einfache Regel befolgt … Ändere deine Kommentare gleichzeitig mit dem Code.

Das ist eine einfache Regel, die Ihnen und Ihrem Team viel erspart Technische Schulden.

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

Kommentare sollten unidiomatischen Code erklären

Manchmal natürlich Vorgehensweise ist nicht richtig. Programmierer müssen die Standards möglicherweise ein wenig „brechen“, aber wenn sie dies tun, ist es ratsam, einen kleinen Kommentar zu hinterlassen, der ihre Gründe 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 waren, waren Sie möglicherweise versucht, ihn zu korrigieren, ohne dass dieser Kommentar dort erklärt, was los ist.

Kommentare können zukünftige Aufgaben identifizieren

Eine weitere nützliche Sache, die man mit Kommentaren machen kann, ist, zuzugeben, dass noch viel zu tun ist.

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

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

Kommentare können auf die Quelle verlinken

Sie haben also gerade eine Lösung für Ihr Problem auf StackOverflow gefunden. Nach dem Kopieren und Einfügen dieses Codes 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.

Pull-Requests schreiben

Anfragen ziehen (PRs) sind ein grundlegender Aspekt jedes Projekts. Sie stehen im Mittelpunkt von Code-Reviews. Und ohne gute Formulierungen können Code-Reviews schnell zu einem Engpass für die Leistung Ihres Teams werden.

Eine gute PR Beschreibung zusammenfasst was Änderung wird vorgenommen und warum es wird gemacht. Große Projekte haben eine Pull-Request-Vorlage, wie diese, die von a angepasst wurde echtes 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:

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

Diese nicht einmal Versuch um zu beschreiben, mit welchem ​​Build, Bug oder Patch wir es zu tun haben. Ein kleines zusätzliches Detail darüber, welcher Teil des Builds behoben, welcher Fehler gequetscht oder welcher Patch hinzugefügt wurde, kann viel dazu beitragen, eine bessere Kommunikation und Zusammenarbeit mit Ihren Kollegen zu etablieren. Es setzt Level und bringt die Leute auf die gleiche Seite.

PR Titel werden traditionell eingeschrieben Imperativ. Sie sind eine einzeilige Zusammenfassung des Ganzen PR, und sie sollten beschreiben was erfolgt durch die PR.

Hier sind einige gute Beispiele:

• Unterstützung benutzerdefinierter srcset-Attribute in NgOptimizedImage
• Standardbildkonfiguration auf 75 % Bildqualität
• Fügen Sie explizite Selektoren für alle integrierten ControlValueAccessors hinzu

Lange vermeiden PRs

Ein Groß PR bedeutet eine riesige Beschreibung, und niemand möchte Hunderte oder Tausende von Codezeilen überprüfen, manchmal nur, um das Ganze zu verwerfen!

Stattdessen könnten Sie:

• kommunizieren Sie mit Ihrem Team durch Fragen,
• Mach einen Plan,
• Zerlegen Sie das Problem in kleinere Stücke, oder
• Arbeite an jedem Stück separat mit seinem eigenen PR.

Ist es jetzt nicht viel sauberer?

Geben Sie Details in der an PR Körper

im Gegensatz zu den PR Titel, der Körper ist Ort für alle Details, einschließlich:

• Warum ist der PR Fertig sein?
• Warum ist dies der beste Ansatz?
• Etwaige Mängel des Ansatzes und Ideen zu ihrer Lösung, falls möglich
• Die Fehler- oder Ticketnummer, Benchmark-Ergebnisse usw.

Fehler melden

Fehlerberichte sind einer der wichtigsten Aspekte eines jeden Projekts. Und alle großartigen Projekte basieren auf dem Feedback der Benutzer. Normalerweise sind es die Benutzer, die selbst nach unzähligen Tests die meisten Fehler finden. Benutzer sind auch große Idealisten, und manchmal haben sie Ideen für Funktionen; bitte hör sie dir an!

Bei technischen Projekten werden all diese Dinge durch das Melden von Problemen erledigt. Ein gut geschriebenes Problem ist für andere Entwickler leicht zu finden und darauf zu reagieren.

Zum Beispiel kommen die meisten großen Projekte mit eine 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 Ihrem das Screen-Shooting-Dienstprogramm des Systems.

Wenn es sich um einen Screenshot von a CLI Programm, stellen Sie sicher, dass der Text klar ist. Wenn es ein ist UI 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 das der Fall ist, versuchen Sie es Nehmen Sie GIFs mit einem Bildschirmaufzeichnungstool auf.

So reproduzieren Sie das Problem

Es ist viel einfacher für Programmierer, einen Fehler zu lösen, wenn er live auf ihrem Computer ist. Aus diesem Grund sollte ein guter Commit die Schritte enthalten, um das Problem genau zu reproduzieren.

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 sich den Fehler eingefangen hat, also können Sie vielleicht einige mögliche Ursachen dafür vorschlagen, warum er da ist. Vielleicht tritt der Fehler nur auf, nachdem Sie auf ein bestimmtes Ereignis gestoßen sind, oder vielleicht tritt er nur auf Mobilgeräten auf.

Es kann auch nicht schaden, die Codebasis zu untersuchen und vielleicht herauszufinden, was das Problem verursacht. Dann wird Ihr Problem viel schneller geschlossen und Sie werden wahrscheinlich dem zugehörigen Problem zugewiesen PR.

Kommunikation mit Kunden

Sie können als Solo-Freelancer arbeiten oder vielleicht der leitende Entwickler in einem kleinen Team sein. Nehmen wir in beiden Fällen an, Sie sind für die Kommunikation mit Kunden in einem Projekt verantwortlich. 

Nun, das Programmierer-Stereotyp ist, dass wir schlechte Kommunikatoren sind. Wir sind dafür bekannt, übermäßig technischen Jargon zu verwenden, anderen zu sagen, was möglich ist und was nicht, und sogar defensiv zu werden, wenn jemand unseren Ansatz in Frage stellt.

Also, wie mildern wir dieses Stereotyp? Fragen Sie Kunden, was sie wollen, und hören Sie immer auf ihr Feedback. Hier ist, wie das geht.

Stellen Sie die richtigen Fragen

Stellen Sie zunächst sicher, dass Sie und der Kunde auf derselben Seite sind:

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

Das Stellen von Fragen 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. Das Stellen von Fragen zwingt diese Person, ihre eigenen Behauptungen zu unterstützen, anstatt sie anzugreifen, indem Sie Ihre eigene Position verteidigen:

• Sind Sie damit einverstanden, auch wenn es mit zusätzlichen Leistungskosten verbunden ist?
• Hilft uns das Verschieben der Komponente dabei, unser Ziel besser zu erreichen?
• Großartig, wer ist dafür verantwortlich, das nach dem Start aufrechtzuerhalten? 
• Wissen Sie auf Anhieb, ob der Kontrast zwischen diesen beiden Farben den WCAG AA-Standards entspricht?

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

Verkauf dich

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

• Wer du bist
• Was tust du
• Warum Sie für den Job gut geeignet sind
• Links zu relevanten Arbeiten, die Sie durchgeführt haben

Und sobald Sie den Job bekommen und einen Vertrag schreiben müssen, denken Sie daran, dass es keinen Inhalt gibt, der einschüchternder ist als ein Haufen juristischer Fachsprache. Obwohl es für Designprojekte geschrieben wurde, ist die Contract Killer kann 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 werden Kunden genauso leicht einen Entwickler einstellen, von dem sie glauben, dass sie gerne mit ihm zusammenarbeiten werden, als denjenigen, der technisch am kompetentesten oder erfahrensten für den Job ist.

Mikrokopie schreiben

Mikroskopie ist die Kunst, benutzerfreundlich zu schreiben UI Meldungen wie Fehler. Ich wette, es gab Zeiten, in denen Sie als Entwickler Fehlermeldungen schreiben mussten, weil sie bis zum Start auf Eis gelegt wurden.

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

Error: Unexpected input (Code 693)

Fehler sind das Letzte, womit Ihre Benutzer sich auseinandersetzen sollen. Aber sie passieren, und wir können nichts dagegen tun. Hier sind einige Tipps, um Ihre Mikroskopierfähigkeiten zu verbessern.

Vermeiden Sie Fachjargon

Die meisten Menschen wissen nicht, was ein Server ist, während 100 % der Programmierer dies wissen. Aus diesem Grund ist es nicht ungewöhnlich, ungewöhnliche Begriffe in einer Fehlermeldung zu sehen, wie z API oder „Timeout-Ausführung“.

Sofern Sie es nicht mit einem technischen Kunden oder Benutzerstamm zu tun haben, ist es wahrscheinlich, dass die meisten Ihrer Benutzer keinen Informatikkurs belegt haben und nicht wissen, wie das Internet funktioniert und warum eine bestimmte Sache nicht funktioniert. Daher der Fehler.

Daher sollte eine gute Fehlermeldung nicht erklären warum etwas schief gelaufen ist, denn für solche Erklärungen könnten beängstigende Fachbegriffe erforderlich sein. Deshalb ist es sehr wichtig, Fachjargon zu vermeiden.

Geben Sie niemals dem Benutzer die Schuld

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-Adresse / Ihr Passwort ist falsch."

Obwohl es dramatisch erscheint zu denken, dass diese Nachricht feindselig ist, fühle ich mich unbewusst dumm. Microcopy sagt, dass es niemals in Ordnung ist, dem Benutzer die Schuld zu geben. Versuchen Sie, Ihre Nachricht in etwas weniger Zeigefinger zu ändern, wie in diesem Beispiel, das aus dem Mailchimp-Login übernommen wurde: „Entschuldigung, diese E-Mail-Passwort-Kombination ist nicht richtig. Wir können Ihnen helfen, Ihr Konto wiederherzustellen.“

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

Überfordern Sie den Benutzer nicht

Die Verwendung von Humor in Ihrer Mikroskopie ist eine gute Idee! Es kann die Stimmung aufhellen und es ist eine einfache Möglichkeit, die Negativität einzudämmen, die selbst durch die schlimmsten Fehler verursacht wird.

Aber wenn Sie es nicht verwenden perfekt, kann es für den Benutzer herablassend und beleidigend wirken. Das ist nur ein groß Risiko einzugehen.

Mailchimp sagt es gut:

Geben Sie sich keine Mühe, einen Witz zu machen – erzwungener Humor kann schlimmer sein als gar keiner. Wenn Sie sich nicht sicher sind, bewahren Sie ein ernstes Gesicht.

(Hervorhebung von mir)

Zugängliches Markup schreiben

Wir könnten leicht einen ganzen Artikel über Barrierefreiheit und ihre Beziehung zum technischen Schreiben verbringen. Verdammt, Barrierefreiheit ist oft in Content Style Guides enthalten, einschließlich derer für Microsoft und Mailchimp.

Sie sind Entwickler und wissen wahrscheinlich schon so viel über Barrierefreiheit. Vielleicht gehören Sie sogar zu den fleißigeren Entwicklern, die Barrierefreiheit zu einem zentralen Bestandteil Ihres Arbeitsablaufs machen. Dennoch ist es unglaublich, wie oft Überlegungen zur Zugänglichkeit auf die lange Bank geschoben werden, egal wie wichtig wir alle wissen, wie wichtig es ist, barrierefreie Online-Erlebnisse zu schaffen, die alle Fähigkeiten einschließen.

Wenn Sie also feststellen, dass Sie das Copywriting einer anderen Person in Ihren Code implementieren, Dokumentation für andere Entwickler schreiben oder sogar schreiben UI Kopieren Sie sich selbst, beachten Sie einige grundlegende Best Practices für Barrierefreiheit, da sie alle anderen Ratschläge für technisches Schreiben abrunden.

Dinge wie:

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

Zusammenfassung

Das waren sechs Wege, die zeigen, wie Technische Redaktion und Entwicklung zusammenfallen. Auch wenn die Beispiele und Ratschläge keine Raketenwissenschaft sind, hoffe ich, dass Sie sie nützlich fanden, sei es unter anderem bei der Zusammenarbeit mit anderen Entwicklern, der Pflege Ihrer eigenen Arbeit, der Notwendigkeit, zur Not Ihre eigene Kopie zu schreiben oder sogar dem Entwurf eines Projektvorschlags Dinge.

Das Fazit: Wenn Sie Ihre Schreibfähigkeiten verbessern und sich beim Schreiben etwas mehr Mühe geben, können Sie tatsächlich ein besserer Entwickler werden.

Ressourcen für technisches Schreiben

Wenn Sie sich für Technische Redaktion interessieren:

Wenn Sie an Texten interessiert sind:

Wenn Sie an Mikroskopie interessiert sind:

Wenn Sie daran interessiert sind, einen professionellen Styleguide zu verwenden, um Ihr Schreiben zu verbessern:

Wenn Sie daran interessiert sind, barrierefrei zu schreiben: