Style Guide zur Dokumentation

Der Style Guide ist sowohl für die Beiträge zur Dokumentation als auch für linguistische Redakteure ausgelegt. Der Style Guide sollte im Sinne der Qualität, Konsistenz und Lesbarkeit des Inhalts überall durchgesetzt werden.

Vorab

• Stellen Sie sicher, dass Sie Ihre Zielgruppe zuerst verstehen. Ihr Inhalt ist verschiedenen Zielgruppen mit unterschiedlichem technischem Hintergrund und verschiedenen Fähigkeiten ausgesetzt. Stellen Sie sicher, dass Ihre Arbeit für sowohl neue als auch erfahrene Leser zugänglich ist.
• Wählen Sie Ihr Thema sorgfältig aus. Ihr Inhalt sollte sich um dieses Thema drehen.
• Stellen Sie sicher, dass Sie die Art Ihres Inhalts verstanden haben. Ist Ihr Inhalt beispielsweise ein Schritt-für-Schritt-Tutorial, eine technische Übersicht oder ein Essay für die breite Öffentlichkeit?
• Bestimmen Sie den Umfang und die Voraussetzungen für Ihren Inhalt.
• Übernehmen Sie einen geeigneten Style Guide.

Allgemeiner Schreibstil und Stil

• Wir ermutigen die Autoren, einfaches Englisch zu verwenden und den Lesern zu helfen, den Inhalt leicht zu erfassen. Es kann hilfreich sein, Ihren Inhalt klar und prägnant zu halten.
• Stellen Sie sicher, dass Ihre Absätze auf ein einheitliches Thema ausgerichtet sind. Ihre Sätze sollten kurz, grammatisch robust und sprachlich konsistent sein.
• Wir empfehlen die Verwendung einer inklusiven Sprachwahl als universellen Ausdrucksstil.

Sprache und Grammatik

• Amerikanisches Englisch ist im Allgemeinen bevorzugt.
• Für einen neuen Begriff klären Sie das Wort ab und geben Sie dann die Abkürzung an. Für gängige Abkürzungen wie RESTful API und HTML ist dies nicht erforderlich.
• Der Ton Ihres Schreibens sollte zum Thema und Zweck passen. Wenn Sie einen persönlicheren Ton erzeugen möchten, verwenden Sie die zweite Person.
• Verwenden Sie nach Möglichkeit die aktive Stimme anstelle der passiven Stimme.
• Verwenden Sie die Gegenwart, um Ihren Entwurf zu schreiben.
• Beachten Sie besonders Ihre Grammatik, dazu gehören:
  • Amerikanische englische Rechtschreibung. Verwenden Sie zum Beispiel "center" anstelle von "centre".
  • Bestimmte und unbestimmte Artikel. Diese Artikel können aus Titeln und Überschriften ausgeschlossen werden.
  • Korrekte Großschreibung. Verwenden Sie die Satzschreibweise für Titel und Überschriften.
  • Pronomen sollten klare Hinweise haben. Zum Beispiel gibt "It is the best exploratory data analysis tool" nicht an, was "it" ist. Um Unklarheiten und Verwirrung zu vermeiden, formulieren Sie den Satz um zu "RATH ist das beste Tool für explorative Datenanalyse".
  • Stellen Sie sicher, dass Ihre Interpunktion gemäß den gängigen Richtlinien korrekt ist.

Überarbeiten Sie Ihren Inhalt

Jetzt, da Sie einen Entwurf haben, sind Sie auf halbem Weg durch den Prozess. Stellen Sie sicher, dass Sie die folgenden sprachlichen Bearbeitungsschritte vor der Einreichung Ihres Inhalts abgeschlossen haben.

• Lesen Sie es noch einmal. Als bewährte Methode finden Sie einen Peer-Reviewer, der Ihnen Feedback geben kann.
• Während des Lesens sollten Sie folgende Punkte beachten:
  • Ist Ihr Inhalt für Ihr Publikum gut verständlich?
  • Ist Ihr Inhalt gut strukturiert?
  • Enthält er Beispiele, die es dem Leser erleichtern, ihn zu verstehen?
  • Sind die technischen Informationen korrekt?
  • Gibt es sensible Informationen, die Sie nicht preisgeben möchten?
  • Am wichtigsten, was lernt Ihr Publikum aus Ihrem Inhalt?

Reichen Sie Ihren Inhalt ein

Das RATH Doc Center verwendet Docusaurus als Content-Management-Plattform.

Sie können Markdown, eine Auszeichnungssprache, die bei vielen technischen Schriftstellern und Programmierern beliebt ist, verwenden, um Dokumente zu erstellen und zu bearbeiten.

Kontaktieren Sie uns, um einen Einreichungsworkflow für Sie einzurichten.