Ist es übertrieben, Styleguides für technisches Schreiben zu befolgen?

Nein, es ist nicht übertrieben, einem Stylebook zu folgen. Wie andere gesagt haben, konsultieren Sie es, wenn Fragen auftauchen, und lernen, während Sie gehen; normalerweise liest man es nicht von vorne bis hinten. Wir alle kleben Haftnotizen auf die oft konsultierten Abschnitte. Da Sie sich die Mühe gemacht haben, Ihre Frage zu stellen, stört Sie offensichtlich die mangelnde Konstanz in Ihrem Unternehmen.

Da Sie viel für Ihren Job schreiben, folgen Sie wahrscheinlich bereits einem Stil. Ich würde vorschlagen, dass Sie beginnen, ein Dokument zusammenzustellen, das all die Dinge enthält, nach denen Sie ständig suchen, und Ihren eigenen Styleguide erstellen. Wer weiß, vielleicht übernimmt Ihr Unternehmen eines Tages Ihren Guide! (Ein Vorschlag: Wenn Sie Ihren eigenen Leitfaden zusammenstellen, notieren Sie sich, auf welcher maßgeblichen Quelle Sie jede „Regel“ basieren, damit Sie bei Bedarf darauf zurückgreifen können.)

Mein Unternehmen folgt dem Associated Press Stylebook , außer wenn dies nicht der Fall ist. Wir haben ein Word-Dokument mit den Ausnahmen, das aktualisiert wird, wenn Entscheidungen getroffen werden. (In der Datei wird immer das Datum vermerkt, an dem eine Regel geändert wird.) Außerdem ändert AP gelegentlich seinen Stil, und meine Firma muss entscheiden, ob sie damit einverstanden sind. Beispielsweise hat AP letztes Jahr von E-Mail auf E-Mail umgestellt . Meine Firma nicht.

Für Dokumentationen, die außerhalb Ihrer Organisation veröffentlicht werden, ist es normalerweise wichtig, einem Styleguide (so ziemlich jedem) zu folgen, damit die gesamte Dokumentation mit einer „Stimme“ gelesen wird, obwohl sie von einer Reihe verschiedener Personen geschrieben wurde. Wie Lauren Ipsum anmerkt, liest man den Styleguide nicht komplett durch, sondern konsultiert ihn zu einzelnen Punkten. (Sie müssen sich jedoch damit vertraut machen, welche Punkte es abdeckt.)

Ich sagte, es ist "normalerweise" wichtig; Sie sollten die Frage zuerst stellen, bevor Sie mit der Annahme eines Leitfadens fortfahren. Es gibt eine bestehende Praxis von „Jeder für sich selbst“; Ist das so, weil es den Verantwortlichen eigentlich egal ist, oder nur, weil die Frage nie aufgekommen ist? Wenn es ihnen nicht wichtig ist, müssen Sie argumentieren, dass es im Verhältnis zu den Kosten für die Einführung einer neuen Praxis von Bedeutung ist. Der Kaufpreis des Buches ist Lärm; die Kosten werden darin bestehen, die Arbeitsgewohnheiten aller zu ändern. Wenn Kunden (oder andere wichtige Personen) diese Dokumentation sehen, ist dies möglicherweise ein einfacher Pitch. Wenn es nur von den Mitgliedern Ihres Teams verwendet wird, spielt es möglicherweise keine Rolle (so sehr es mich als Autor schmerzt, das zu sagen).

Ich glaube, Sie verwechseln einen Styleguide mit einem Stilhandbuch. Das Chicago Manual of Style wird Ihnen dabei helfen, ist aber eher ein Nachschlagewerk für Best Practices als eine Reihe von Richtlinien und Verfahren zur Anleitung von Dokumententwicklungsprozessen für Ihre spezielle geschäftliche Nutzung.

Es scheint, dass Sie einen Styleguide erstellen und unternehmensweit implementieren möchten, etwas, das Dinge wie Abschnitte in einem Bericht oder Benutzerhandbuch, verwendete Schriftarten, die Verwendung von Logos und Marken, Software zur Erstellung von Dokumentationen und Vorlagendesign standardisiert Normen. Führen Sie eine Websuche nach „technical style guide“ durch und Sie werden Beispiele finden.

Das Erstellen des Styleguides wird jedoch nicht Ihre größte Aufgabe sein. Das Management dazu zu bringen, es als Anforderung umzusetzen, wird die größte Herausforderung sein, und wenn Sie das nicht haben, werden Sie Ihre Arbeit verschwenden und sich selbst und Ihre Kollegen ärgern. Der Schlüssel zum Einverständnis des Managements besteht darin, ihm verständlich zu machen, dass eine konsistente Dokumentation Teil eines konsistenten Brandings und einer konsistenten Botschaft ist – Ihre Dokumentation ist ein Teil der Marketingbemühungen.

Sobald Sie das Management hinter Ihren Bemühungen haben, binden Sie Ihre Kollegen ein und arbeiten Sie als Team, um einen Stilleitfaden zu erstellen, der auf Ihre Unternehmenskultur und Ihre Arbeitsabläufe zugeschnitten ist. Beziehen Sie auch wichtige Mitglieder der Technik-, Kundendienst- und Marketingteams in diese Bemühungen ein, damit Sie die Technik mit der Planung der Vorlaufzeiten für die Dokumentation auf die gleiche Seite bringen und erfahren, was in der Dokumentation Kunden verwirrt oder frustriert, von den Leuten, die es tun müssen Gehen Sie regelmäßig mit ihnen um und stellen Sie sicher, dass die Begriffe, die Sie in der Dokumentation verwenden, dieselben sind, die die Marketingabteilung verwendet, und dass Sie die richtige Zielgruppe ansprechen, indem Sie den tatsächlichen Kundenstamm und ihre reale Nutzung der Produkte verstehen.

Einige Styleguides decken auch Dokumentverteilungsprozesse und Aufbewahrungsrichtlinien ab. Diese können auch in separaten Verfahren behandelt werden, die am besten zu Ihrer geschäftlichen Nutzung passen.

Überhaupt nicht übertrieben. Das Chicago Manual of Style ist jedoch nicht wirklich ideal für technisches Schreiben (und ist als Referenz zum Nachschlagen gedacht, nicht als umfassende Lektüre). Es ist ein guter Leitfaden für allgemeines, formelles Schreiben für Amerikaner. Für ein internationales Publikum ist das Äquivalent The Oxford Guide to Style (alias New Hart's Rules , auch als Hälfte des Oxford Style Manual veröffentlicht ).

Das Hauptproblem mit Chicago besteht darin, dass seine Herausgeber entschieden gegen die Verwendung von logischen Zitaten sind (dh nichts in die Anführungszeichen einfügen, was nicht im Originalzitat enthalten war), außer für "Textkritik" und "Computercode und -befehle". Ansonsten empfehlen sie nichts anderes als die Zitierzeichensetzung im Stil des amerikanischen Journalismus und der Belletristik, bei der Punkte (Stopps, Punkte) und Kommas immer innerhalb des Anführungszeichens stehen, auch wenn sie logisch nicht dorthin gehören. Dies ist eine schreckliche Idee in jeder technischen oder anderen präzisen Form des Schreibens, obwohl sie vom AP Stylebook und anderen amerikanischen journalistischen Stilhandbüchern immer noch bevorzugt wird.

Wenn technisches Schreiben Ihre Aufgabe ist, würde ich Ihnen raten, die Handbücher von Chicago , Oxford und AP zu besitzen (sowie alle anderen Styleguides, die Sie benötigen, z. B. das legale Bluebook und Redbook und das Oxford-Äquivalent OSCOLA , das ein kostenloses PDF ist ; und/oder die CSE- , AMA- und APA -Styleguides für Wissenschaft/Medizin). Passen Sie Ihren Stil nach Bedarf an. Für geschäftliche Kommunikation mit Amerikanern verwenden Sie Chicago ; für PR-Materialien, die für Amerikaner bestimmt sind, verwenden Sie AP ; Verlassen Sie sich für ein internationales Publikum auf Oxford(auch beim Zitieren mit hoher Genauigkeit, z. B. getippte Befehle oder die Beschriftungen von Gerätesteuerungen). Wenden Sie sich bei Bedarf für wissenschaftliches Schreiben an CSE usw. Sie könnten manchmal auch aufgefordert werden, das MLA Style Manual für bestimmte Zwecke einzuhalten. Diese Bücher sind allesamt eine gute Investition für jeden professionellen Autor von Sachbüchern. Das gilt auch für die Aktualisierung auf neue Ausgaben, sobald sie veröffentlicht werden; manchmal sind die Änderungen erheblich (obwohl es einige Jahre dauern kann, bis sie sich ausbreiten). Der effektive Sprachgebrauch ist ein bewegliches Ziel.

Kauf es? Ja. Ich glaube nicht, dass Sie es von vorne bis hinten lesen müssen, es sei denn, Sie sind ein ernsthafter Sprachfreak, der Wörterbücher zum Spaß liest. ::Hust hust::

(Ziehe meine 14. Ausgabe als Referenz heraus ...)

Ich würde versuchen, so viel wie möglich von „Die Teile eines Buches“ und „Manuskriptvorbereitung“ zu lesen, bevor Ihre Augen glasig werden. Sofern Sie nicht die Arbeit eines anderen lesen, können Sie den Abschnitt zum Korrekturlesen überfliegen. „Design und Typografie“ wäre auch gut zu lesen.

Alles andere können Sie nachschlagen, wenn Sie darauf stoßen: Verwende ich das serielle Komma? Nimmt dieser Satz "was" oder "das"? Wie zitiere ich eine Website in einem Literaturverzeichnis?

Ich denke nicht, dass es übertrieben ist, einem Styleguide zu folgen. Es ist wirklich hilfreich, eine verbindliche Antwort auf Dinge wie E-Mail oder E- Mail zu haben und sie nicht dutzendmal nachschlagen oder mit anderen Leuten darüber streiten zu müssen. CMOS ist jedoch wahrscheinlich zu detailliert für Ihre Anforderungen, und ich würde es sicherlich nicht von Anfang bis Ende lesen. Selbst als jemand, dessen Hauptberuf das Schreiben ist, würde ich mich nicht hinsetzen und einen Styleguide von vorne bis hinten lesen. Für einen Elektroingenieur denke ich nicht, dass das eine gute Verwendung seiner Zeit ist.

Derzeit habe ich in meinem Bücherregal The AP Stylebook und The Microsoft Manual of Style. Ich mag beides, obwohl AP keine Kommas verwendet und ich persönlich Kommas mag. Microsoft ist sehr hilfreich für Softwareanweisungen, da es definiert, wie Tasten-, Fenster-, Bildschirm- und Menünamen formatiert werden.

Es könnte tatsächlich nützlicher sein, einen eigenen Styleguide zu schreiben und eine Vorlage für die Dokumente zu erstellen, die Sie am häufigsten schreiben. Der Styleguide kann eine einfache Liste von Stilentscheidungen sein; es muss nicht alles unter der Sonne umfassen. Wenn ich Benutzerhandbücher schreibe, liste ich alle Teile der Benutzeroberfläche auf und wie man diese Begriffe gestaltet. (Wenn die Anwendung zum Beispiel eine kleine 3D-Karte für die Navigation hat, notiere ich, ob sie die Mini-Karte, die Mini-Karte, die 3D-Karte, die Navigationskarte oder was auch immer heißt.) Ich füge auch alle Begriffe hinzu, die dazu kommen mehr als eine Standardschreibweise oder Silbentrennung haben. Jedes Mal, wenn ich beim Schreiben oder Bearbeiten eine Frage zu einem Begriff habe, füge ich sie der Liste hinzu, sobald ich sie gelöst habe.

Sie können diesen Styleguide nur für sich selbst verwenden oder ihn mit dem Rest Ihres Teams teilen, je nachdem, wie viel Einfluss Sie haben und wie sehr Ihre Organisation Wert auf Konsistenz beim Schreiben legt.

IEEE-Standards sind eine gute Ressource für die Entwicklung von Vorlagen, da ihr Standard für ein bestimmtes Dokument normalerweise eine Mustergliederung und eine Beschreibung des Inhalts für jeden Abschnitt enthält. Es ist im Allgemeinen nicht allzu schwierig, ein Word-Dokument mit der gewünschten Formatierung, den Abschnitten, die alle angeordnet sind, und Kommentaren, die angeben, was in diesen Abschnitten tatsächlich stehen soll, einzurichten.

Wenn die Dokumentation immer nur von einer Person geschrieben und von derselben Gruppe von Personen gelesen wird, erfordert diese Dokumentation keinen Stil (vorausgesetzt, es handelt sich um eine interne Dokumentation, die nicht an Kunden geht). Solange beide Seiten es verstehen, kann es funktionieren, obwohl es für Neulinge beim Lesen eine Weile dauern kann, bis es verstanden wird. Wenn es für diese Situation funktioniert, es in biblischem Griechisch zu schreiben, gibt es keine Probleme damit.

Fast alle Dokumentationen, auch interne, werden jedoch von mehr als einer Person geschrieben und im Laufe der Zeit von verschiedenen Personen gelesen. Es kann sich um Anweisungen zum Testen handeln, aber QA-Auditoren müssen sie möglicherweise auch sehen. Unterweisungsdokumente können zunächst für bestimmte Gruppen bestimmt sein, können dann aber für neue Personen gespeichert werden. Daher ist eine Art von Standards eine gute Idee, obwohl sie möglicherweise nicht so streng sein müssen wie für externe Benutzer.

Der Zweck besteht nicht darin sicherzustellen, dass alles immer konsistent und professionell ist, sondern sicherzustellen, dass neue Personen die Dokumentation richtig verstehen und interpretieren können. Kleine Tippfehler sind also nicht so wichtig, aber Klarheit und Konsistenz sind es.

Das AP ist dem Chicago Manual of Style sehr ähnlich , aber viel einfacher zu bedienen. Warum gegen den Strich gehen? Sie werden mit dem AP das größtmögliche Publikum erreichen, was meiner Meinung nach das ultimative Ziel hier sein sollte.

CMOS hat keinen wirklichen Wert für Sie. Und ich bin ein lebenslanges Mitglied von IEEE, aber sie machen viele Dinge, die bürokratisch und wach sind, aber keinen wirklichen Wert für die Mitglieder haben.

Ihr Unternehmen sollte einen Styleguide bereitstellen, der viel kleiner ist, aber die Aufgabe erfüllt, die es benötigt.

Das Formatieren von Dokumenten ist nicht gerade Stil, wie ich die Worte verwende. Und wäre eine der Bearbeitungsfunktionen ganz unten in der Liste und weit über den eigentlichen Schreibaufwand hinaus.

Wenn die Formatierung das eigentliche Problem ist, müssen sie eine Vorlage bereitstellen, die Sie bei der Strukturierung der von Ihnen geschriebenen Ergebnisse unterstützt.

Das eigentliche Problem klingt eher nach Bearbeitungsebenen. Und was Redakteure auf diesen Ebenen (oder Sie) tun.

Liegt das Problem in der Struktur, dann könnte eine Vorlage die Notwendigkeit für einen Entwicklungsredakteur beseitigen, den Bericht auf hoher Ebene zu strukturieren, bevor Sie beginnen. Versuchen Sie das niemals, nachdem Sie geschrieben haben!!

Wenn Stil wirklich das Problem ist, dann sollten sie eine Redaktionsabteilung haben, die die technischen Berichte in einen „Standard“ umwandelt.

Line Editing, Copy Editing, SPAG-Checks und Low-Level-Sachen sind auch kein Style, aber auch wichtig.

Der Versuch, Ingenieuren einen CMOS-ähnlichen Leitfaden aufzuzwingen, wäre störend und kontraproduktiv.

Suchen Sie nach einigen Mustertestberichtsvorlagen und wählen Sie eine aus, die Ihnen gefällt, und schlagen Sie dann vor, dass das Management erwägen sollte, alle Berichte diesem Modell folgen zu lassen.

Wenn Ihr Anliegen etwas anderes ist, stellen Sie bitte eine andere, direkter auf das Problem bezogene Frage und sagen Sie uns genau, was das Problem ist, das Sie mit Berichten haben.