Kann Technisches Schreiben weniger saugen

Das Wichtigste, was Sie über technisches Schreiben wissen müssen, ist, dass die Leute es nicht um seiner selbst willen lesen. Sie lesen es, weil sie versuchen, etwas zu tun, und sie mehr Informationen benötigen. Das Schreiben muss nicht fesseln oder unterhalten, da der Leser bereits mit der Aufgabe beschäftigt ist. Es ist ihre Auseinandersetzung mit der Aufgabe und ihr Informationsbedürfnis, die sie zum Weiterlesen antreibt, nicht die Auseinandersetzung mit dem Text.

Und aus diesem Grund sollte die technische Redaktion nicht versuchen zu fesseln oder zu unterhalten. Alles, was Sie in diesem Bereich tun, steht nur dem im Wege, was der Leser möchte: die Informationen zu erhalten, die er benötigt, um zu seiner ursprünglichen Arbeit zurückzukehren.

Schlichtheit und Klarheit in Instruktion und Beschreibung sind daher zentrale Tugenden in der Technischen Kommunikation. Das sollte die Technische Redaktion jedoch nicht zu einem langweiligen Job machen. Vielmehr stellt es eine andere Reihe von Schreibherausforderungen dar.

Ideen, Konzepte und Aufgaben klar und deutlich zu machen, ist eine Herausforderung für sich. Und da der Leser oft mit falschen Vorstellungen darüber, wie die Dinge funktionieren sollten, zur Dokumentation kommt, besteht eine echte Herausforderung darin, sie und ihre Denkprozesse einzubeziehen und ihre Füße auf den richtigen Weg zu bringen, insbesondere wegen ihrer Einstellung "Sag mir einfach, welchen Knopf ich drücken soll!"

Denken Sie schließlich daran, dass Ihr Ziel bei allen anderen Formen des Schreibens darin besteht, die Aufmerksamkeit des Lesers zu erregen und aufrechtzuerhalten, während das Ziel beim technischen Schreiben darin besteht, ihn so schnell wie möglich wieder zu dem zu bringen, was er gerade getan hat. Je weniger Zeit sie mit Lesen verbringen und je mehr Zeit sie erfolgreich damit verbringen, desto besser ist Ihre technische Redaktion.

Diese Frage berührt einen der zentralen Gedanken der Technischen Redaktion: das themenbasierte Schreiben .

Ihr Paradigma-Beispiel „1. einstecken 2. verbinden 3. anschauen.“ ist ein Exemplar des Themas "Aufgabe", aber es gibt auch (mindestens) 2 andere Typen, nämlich "Konzept" und "Referenz".

Das Hinzufügen eines kurzen Konzeptthemas, das die Vorteile der Durchführung der Schritte 1-3 beschreibt, wäre ansprechender und würde absolut in den Aufgabenbereich der technischen Redaktion fallen.

Technisches Schreiben zielt darauf ab, die Perspektive des "Benutzers" einzunehmen, was auch immer er "benutzt". Es hat also das Potenzial, sehr einfallsreich und kreativ zu sein.

Ein Beispiel, das mir in den Sinn kam, sind die Anweisungen oder "Regeln" für Spiele. Einige dieser Bücher können so fesselnd sein, dass viele Fans nur die Regelbücher lesen, ohne die Spiele tatsächlich zu spielen (ich weiß, dass ich das getan habe, und ich bemerke, dass Leute in Diskussionsforen für zB Rollenspiele von der gleichen Faszination berichten).

Ich stimme @mbakeranalecta grundsätzlich zu, aber ich würde sanft die Idee bestreiten, dass der Leser immer mit der Aufgabe beschäftigt ist, die Sie gerade erklären - ein Teil der Aufgabe des Schreibens von Hilfe oder FAQ besteht darin, dem Leser dabei zu helfen, herauszufinden, welches Problem er hat tatsächlich versucht zu lösen; Je komplexer das Thema, desto schwieriger ist es, Ihre Wissenslücke zu identifizieren, und desto mehr Vorstellungskraft wird es brauchen, um den Leser von „dort“ nach „hier“ zu bringen.

Ich denke, was Sie vermissen, ist, dass alles Schreiben eine Geschichte erzählt. Nur weil es keine Liebesgeschichte oder Verfolgungsjagd gibt, bedeutet das nicht, dass Ihre technische Redaktion keine Geschichte erzählt. Sie erzählen gerade die Geschichte vom Anschließen eines Chromecast. Das ist eigentlich eine spannende Geschichte für Leute, die gerade einen Chromecast bekommen haben. Sie sind deine Charaktere! Verringern Sie ihre Aufregung nicht mit beschissenem Schreiben. Freuen Sie sich mit ihnen – wir sind Chromecasting! – so wie Sie sich zusammen mit einer fiktiven Figur aufregen würden, die sich verliebt oder ein Abenteuer erlebt.

Bekommen Sie einen klaren Kopf, steigen Sie in die Geschichte ein und schreiben Sie dann einen sympathischen, prägnanten, hilfreichen, leicht verständlichen und für alle verständlichen Leitfaden zu Chromecasting, der Spaß macht, ihn zu lesen und zu verwenden, und der das Leben der Menschen verbessert, indem sie ihre neue Chromecast-Einrichtung vornehmen zu einem lustigen Ereignis mit vielleicht einer kleinen Falle hier und da, die leicht zu lösen war, anstatt einer schrecklichen Pflicht, die ihnen Stunden ihres kostbaren Lebens raubte und sie dann enttäuscht zurückließ.

Anstelle einer fiktiven Figur, die darauf wartet, dass Sie ihnen sagen, was sie tun sollen, haben Sie eine Gemeinschaft echter Charaktere, die darauf warten, dass Sie ihnen sagen, was sie tun sollen. Mit großartigem Schreiben können Sie Millionen Leben verbessern. Es ist eine ernsthafte Verantwortung und eine großartige Gelegenheit, als Autor und als Mensch zu wachsen.

Ich stimme @mbakeranalecta zu, dass der Zweck des technischen Schreibens nicht darin besteht, zu unterhalten, sondern zu informieren.

Ich erinnere mich an ein Lehrbuch über Softwareentwicklung, das ich auf dem College hatte, wo der Text regelmäßig mit kleinen Geschichten über „Sallys erster Tag als Programmiererin“ und ähnliches unterbrochen wurde. Diese Geschichten sollten vermutlich den Text beleben und gleichzeitig Aussagen aus dem Kapitel veranschaulichen. Mir persönlich war der Autor nur peinlich. Die Geschichten waren nicht nur größtenteils irrelevant, sondern auch lahm und süßlich. „Oh, wie aufregend es ist, in der realen Welt der Softwareentwicklung zu arbeiten!“, rief Sally aus. Es war einfach dumm.

Trotzdem denke ich, dass es gut sein kann, die Langeweile von trockenem Material hin und wieder zu durchbrechen. Ich habe ein Datenbankbuch geschrieben, in dem ich einen Karikaturisten dazu gebracht habe, einige Karikaturen für mich zu zeichnen, von denen ich glaube, dass sie nicht dumm sind, vielleicht eine für jedes oder zwei Kapitel. Ich habe einmal ein Benutzerhandbuch geschrieben, in dem ich in dem Abschnitt, in dem beschrieben wird, wie Benutzer zum System hinzugefügt und gelöscht werden, den Abschnitt zur Wiederherstellung eines gelöschten Benutzers einleitete, indem ich sagte: „Wenn Sie einen Benutzer löschen, kommen sie angekrochen und betteln um ihre alten Job zurück, Sie können den Benutzer wiederherstellen, indem Sie ..." Okay, nicht die Art von Witz, der die Leute vor Lachen brüllen wird, aber ich dachte, es war ein Kichern wert und half, die Stimmung aufzuhellen. Ich finde sowas hilfreich.

Aber ich würde sehr darauf achten, solche Dinge nicht zu übertreiben. Ein kleiner Witz alle zehn Seiten kann die Stimmung aufhellen. Auch wenn die Witze nicht sehr gut sind, wird der Leser wahrscheinlich nichts dagegen haben. Es ist eine Pause. Aber wenn Sie es ständig tun, werden die Leser irgendwann sagen: "Hey, ich versuche zu lernen, wie man einen Foobar bedient, und höre nicht einen Haufen Ihrer lahmen Witze."

Ich würde sagen, zuerst dein Ego aus der Gleichung herauszunehmen. Technische Dokumentation dient einem bestimmten Zweck, nämlich der Vermittlung von Informationen aus einer maßgeblichen Quelle an einen Leser. Überflüssige Informationen wie Humor lenken ab.

Angenommen, ich möchte meinen DVD-Player an meinen neuen Flachbildfernseher anschließen. Ich möchte nichts darüber hören, wie Ihr Großvater Farbe verkackt hat, als RCA sie eingeführt hat. Wie hilft mir das, die Aufgabe zu erledigen? Hier sind die Kriterien für technische Dokumente in der Reihenfolge ihrer Wichtigkeit:

Ist es genau? Ist es vollständig? Ist es angemessen?

Bleiben Sie bei der Aufgabe und den Fakten. Wenn Sie neu im Spiel sind, finden Sie einen guten Redakteur, hoffentlich einen, der sich auf diesem Gebiet auskennt, und achten Sie auf seine Kommentare.

Ich würde grundsätzlich der akzeptierten Antwort zustimmen, dass das Hauptziel der technischen Redaktion darin besteht, jemandem bei einer Aufgabe zu helfen, und darauf sollte sie sich konzentrieren. (Meistens) möchten Sie eine bestimmte Aufgabe schnell erledigen. Ich würde sagen, das meiste davon gilt für Online-Dokumentationen, die knapp sein müssen, wie kurze Anleitungen oder Referenzen.

Ich bin allerdings anderer Meinung , dass dies für alle technischen Dokumentationen gelten muss und man sich immer auf Trockenheit beschränken muss. Ich sehe keinen Schaden darin, informiert und unterhalten zu werden (wenn möglich).

Ich denke, es gibt mehrere Möglichkeiten, etwas Spaß in die Dokumentation zu bringen.

• Verwenden Sie ein gutes Design, das die Dokumente leicht lesbar und ästhetisch ansprechend macht
• Fügen Sie Bilder (und/oder Videos) hinzu, um Dinge zu visualisieren
• Das Problem mit Humor ist, dass ihn nicht jeder zu schätzen weiß. Aber wenn Sie Ihr Publikum gut kennen, denke ich, dass ein Wortspiel oder Comic ab und zu nicht schaden kann, wenn es passt, Beispiel: https://pbs.twimg.com/media/DldA_cIXgAADj5w.jpg
• Ein weiteres Beispiel für Knappheit und Spaß beim Anschauen sind einige technische Sketchnotes. Die Technik kann sich für Spickzettel als nützlich erweisen
• Fügen Sie Analogien und Bilder hinzu, um die Dinge zu erklären, Beispiel: Eine Einführung in HTTP/2 für SEOs

• Quelle: https://xkcd.com/293/
• Lizenz: https://xkcd.com/license.html

Wenn Sie Programmierkenntnisse haben, werfen Sie einen Blick auf Kernighan und Ritchie .

Ich schwöre, dass die Hälfte des Grundes, warum Unix so populär wurde, die wirklich erstaunliche Qualität dieses Buches und einiger anderer war, die es mögen! Ich weiß, dass es mich definitiv inspiriert hat!

Versuchen Sie im anderen Extrem, sich Unix/Linux-Manpages anzusehen, die zwar klar sind, aber fast nie etwas erklären oder sogar Verwendungsbeispiele bieten.

Viele Programmierer wollen sich einfach nicht die Zeit nehmen, niederen Wesen Dinge zu erklären, oder sie finden es sehr schwierig.

Sobald Sie genug wissen, um etwas zu entwerfen und zu implementieren, wissen Sie viel mehr als jeder typische Benutzer davon jemals wird (oder möchte!). Es sind so viele Facetten und zugrunde liegende Hintergrundfähigkeiten erforderlich, dass viele davon erforderlich sind, um kompetent zu sein zur zweiten Natur werden, oder, um eines der schädlichsten Wörter in der englischen Sprache zu verwenden, "offensichtlich". Wenn Sie sich als Programmierer (oder einem anderen intensiven Fachgebiet) so etwas nähern und es auf das reduzieren, was Sie für die Grundlagen halten, kann es für einen Benutzer immer noch unverständlich oder zumindest verwirrend sein.

Außerdem würden Sie wahrscheinlich nicht daran arbeiten, wenn Sie nicht bereits verstanden hätten, welche Probleme es lösen wird und warum Sie es verwenden möchten. Solche Dinge werden vom Programmierer angenommen, bevor sie sich überhaupt entwickeln, und werden etwas unbewusst oder "offensichtlich".

Es kann eine große Aufgabe sein, zu erkennen, was die meisten Ihrer Zuhörer wahrscheinlich wissen und verstehen würden, und dann die Dinge bereitzustellen, die notwendig sind, um die Lücke zwischen ihnen und den von Ihnen präsentierten technischen Informationen zu schließen.

Wenn Sie zu wenig präsentieren, werden einige Leser verloren oder fehlgeleitet (siehe viele SE-Fragen, in denen die Leute nach diesen niedlichen kleinen Kauderwelschketten fragen, die wirklich Gabelbomben sind - von denen einige bereits den Computer des OP zum Absturz gebracht haben.)

Wenn Sie zu viel präsentieren, hören die Leute auf zu lesen, fühlen sich beleidigt, verlieren sich in irrelevanten Details oder murmeln Ihnen Dinge über TL;DR zu!

Es ist eine ganz besondere (wenn auch meist unbesungene und unterschätzte) Leistung, etwas so zu schreiben, dass jemand, der es liest, etwas davon sagt wie „Ich wusste nicht, dass es das kann!“, „Ich kann warten Sie nicht, es selbst zu versuchen!, oder "Jetzt verstehe ich!"

Sie haben vielleicht keine Drachen zu töten, aber wenn Sie jemandem das Selbstvertrauen geben können, sich sogar einem Monster wie Gimp oder Inkscape zu nähern (das sind die Dinge, die ich normalerweise in Schränken aufbewahre, die ich fürchte, zu öffnen!), dann ist das so eine große Sache.

Es gibt einen riesigen Raum für technische Redakteure, die Dinge tatsächlich erklären und lehren können – und nicht nur dokumentieren!

Eine Möglichkeit, die ich benutze, ist, zwischendurch einen kleinen Witz zu machen. Wie 1. Einstecken. 2. Mach es noch einmal, diesmal verkehrt herum, du hast es. 3. Verbinden. 4. Beobachten.

Burgess hat so etwas in Earthly Powers verwendet . Der Protagonist hatte sich ein künstliches Bein gegriffen und Burgess beschrieb, wie er es als Waffe handhabte (der technische Punkt) und dann sagte er, dass es so sei, als wäre er ein Verkäufer von künstlichen Beinen und dachte so etwas wie „Hier, Dame, schauen Sie sich die Qualität an dieses Bein, das beste Bein, das du finden wirst', und dann schwingt er es gegen eine Person. (Dies ist nicht das genaue Zitat.)

Oder Sie können eine Beschreibung dazwischen schreiben, wie z

X las das Handbuch '1. Steck ein, sagte es. X steckte es ein. „Schön. Nächster Schritt jetzt: 2. Connect'. 'Gut! Lass uns verbinden...'

usw.

Dies ist etwas, das Sie ganz einfach tun können und das Interesse des Lesers aufrechterhalten.

Klarheit in Ihrer Technischen Redaktion sollte immer oberste Priorität haben, aber das bedeutet nicht, dass Sie die emotionale Bindung zum Leser opfern müssen.

Ich denke, ich würde einen Ansatz wählen, der dem ähnlich ist, wie einige Websites das Verfassen von Texten praktizieren. Als Texter würden Sie sich nicht vorstellen, dass Sie die Geschichte von Chromecast erzählen, der den Fernseher verrät. Stattdessen würden Sie sich vorstellen, dass Sie den Dialog für eine einzelne Rolle in einem Drama schreiben, das sich im Leben Ihres Lesers abspielt. Ihr Leser ist die Hauptfigur in dieser Geschichte. Sie, bzw. Ihr Handbuch, sind der hilfreiche Freund. Das große, frustrierende, technische Ding, das sie aufzustellen versuchen, ist der Antagonist.

Wenn Sie so schreiben, denken Sie daran, dass die Geschichte bereits ohne Sie begonnen hat, bevor der Leser das Benutzerhandbuch in die Hand genommen hat. Sobald sie anfangen zu lesen, ist es Ihre Aufgabe, den emotionalen Zustand zu erwarten, in dem sie sich befinden, und zu versuchen, ihn zu verstärken, wenn er positiv ist, oder ihn zu zerstreuen, wenn er negativ ist.

Versuchen Sie, über die Situation nachzudenken, in der sich Ihr Leser befindet. Sind sie frustriert, dass sie etwas nicht zum Laufen bringen können? Oder sind sie super begeistert, dass sie gerade ein neues Spielzeug zum Spielen bekommen haben? Passen Sie Ihre Stimme und Ihren Ton an die wahrscheinliche Situation an. Möglicherweise müssen Sie sogar Ihren Ton im gesamten Handbuch anpassen. Zum Beispiel könnte die Einführung lebhafter und enthusiastischer sein, aber ein Abschnitt zur Fehlerbehebung könnte in einen sympathischeren Ton übergehen.

Sie müssen keine Witze reißen oder flauschige Extras hinzufügen, die den Leser nicht zum Ziel bringen. Aber Sie müssen verstehen, wer Ihr Leser ist, was er tut und warum er es tut. Damit können Sie erraten, von welcher Art von Person sie in ihrer aktuellen Situation Hilfe benötigen würden - Papa? ein Arzt des Vertrauens? Ihr Kumpel von der Arbeit, der sein System erst gestern eingerichtet hat? Sobald Sie herausgefunden haben, wer das ist, verwenden Sie die Stimme dieser Person. Denken Sie über den Grad der Formalität bei der Wahl der Wörter und die Komplexität Ihrer Satzstruktur nach.

Wenn ich möchte, dass mein Vater mir etwas erklärt, möchte ich vielleicht zusätzliche Details, damit ich lernen kann, wie man das Ding alleine macht. Wenn ich möchte, dass mir ein Arzt etwas erklärt, erwarte ich mehr Fachsprache (wenn es zu einfach wäre, würde ich dem Arzt möglicherweise nicht vertrauen!). it done - ganze Sätze, aber keine zusätzlichen Leckerbissen darüber, warum es funktioniert.

MailChimp (ein Online-Newsletter-Zustelldienst) zeichnet sich dadurch aus, dass er auf seiner Website eine konsistente, freundliche Stimme verwendet, selbst wenn es um technische Dinge geht. Sie passen den Ton an die Umstände an, damit die Leser nie einen abgedroschenen Witz in einer Fehlermeldung hören. Während sie vielleicht überflüssige Witze machen, stehen sie dem Verständnis nie im Weg.

Der Voice and Tone Guide von MailChimp ist ein ausgezeichneter Ort, um sich mit dem Schreiben dieser Art vertraut zu machen.

Hier gibt es viele tolle Antworten. Eines der besten Beispiele für kreative Benutzerhandbücher, auf die ich in letzter Zeit gestoßen bin, ist dieses: http://jamhub.com/docs/JamHubOwnersManual_English.pdf

Sie haben großartige Arbeit geleistet, indem sie für hochtechnische Benutzer geschrieben haben, die die technischen Details lieben und nicht herabgeredet werden möchten, und für Benutzer im Plug-Play-Stil, die nur mit dem Produkt loslegen möchten, aber davon verwirrt wären technisches Zeug.

Zeigt, was möglich ist, wenn Sie an Ihr Publikum denken!

Ich hoffe, das hilft.

Wie peppen Sie die Inhaltserstellung auf, wenn Sie technische Anleitungen schreiben? Nun, Sie können offensichtlich nicht zu viele Beinamen oder Metaphern verwenden. Emotionen haben in technischen Dokumenten wenig Platz. Einige Unternehmen versuchen jedoch, die Technische Redaktion als Instrument zu nutzen, um das Image ihres Unternehmens aufzubauen oder weiter zu fördern.

Ein guter Sinn für Humor kann beispielsweise eine Eigenschaft sein, für die Ihr Unternehmen bekannt ist. Und das bedeutet, dass sogar Ihre Hilfethemen ein paar Witze enthalten können. Google macht das zum Beispiel in Online-Dokumentationen. Google hat jedoch ein ganzes Expertenteam, das versucht herauszufinden, was angemessen ist. Darüber hinaus untersuchen diese Experten auch andere Kulturen, um sicherzustellen, dass Lokalisierungen den ethischen und kulturellen Besonderheiten verschiedener Länder entsprechen.

Nicht jedes Unternehmen verfügt über die Ressourcen, die Google hat. Um also keinen negativen Eindruck zu hinterlassen, entscheiden sich die meisten Menschen dafür, in ihren Bedienungsanleitungen auf der sicheren Seite der Dinge zu bleiben.

Ich empfehle Ihnen, diesen Artikel zu lesen – „ How to Up the Drama in Your Technical Documentation “, um mehr zu diesem Thema zu erfahren.