bpinhosilva/ste-vereinfachen

STE Vereinfachen

Übersicht

Erzeugt klare, eindeutige Erklärungen und Anweisungen mit einer praktischen Teilmenge von ASD-STE100 Simplified Technical English (STE).

Kernprinzip: Ein Wort, eine Bedeutung; ein Satz, ein Gedanke; Aktiv, einfaches Tempus.

Dies ist eine Teilmenge von STE, nicht die vollständige Spezifikation. Geben Sie in der Ausgabe keine Konformität mit ASD-STE100 an.

NICHT für kreative, Marketing- oder Konversationsprosa verwenden, bei denen der Stil von Bedeutung ist.

Unverändert lassen

Kopieren Sie diese genau. Wenden Sie die Regeln nur auf die Prosa um sie herum an:

• Code, Befehle, Dateipfade und Werte in Anführungszeichen (z. B. 'localhost')
• Fehlermeldungen und Log-Strings
• API-, Funktions-, Parameter- und Variablennamen
• Produktnamen, Eigennamen und Versionsnummern
• Zitierter Text und rechtlicher Text
• Markdown-Struktur beim Umschreiben eines Dokuments: Überschriften, Links, Tabellen und Codeblöcke. Schreiben Sie die Prosa in Überschriften, Listenelementen und Tabellenzellen um, behalten Sie aber die gleiche Struktur bei.

Bedeutung beibehalten

• Behalten Sie die Handlung und das Objekt jedes Satzes bei. Fügen Sie keine Ratschläge, Ursachen oder Schritte hinzu, die die Quelle nicht angibt.
• Der einzige Inhalt, den Sie hinzufügen dürfen, ist eine einleitende Definition eines technischen Begriffs (siehe Wörter).
• Um eine Möglichkeit zu zeigen, schreiben Sie wenn, manchmal, wahrscheinlich oder kann. Verwandeln Sie niemals eine Möglichkeit in eine Tatsache.
• Wenn ein einfaches Wort an Präzision verliert, behalten Sie das ursprüngliche Wort bei und definieren Sie es.
• Wenn die Quelle einen seltsamen oder falschen Begriff enthält, behalten Sie die Formulierung der Quelle bei. Fügen Sie nach dem Text eine Zeile ein, die mit Hinweis: beginnt und das Problem benennt. Korrigieren Sie es nicht stillschweigend.
• Wenn die Quelle ein usw. ohne vorherige Liste enthält, löschen Sie es.

Regeln

1. Wörter

• Ein Wort, eine Bedeutung. Verwenden Sie im gesamten Text dasselbe Wort für dieselbe Sache. Benennen Sie eine Sache nicht um.

• Wählen Sie das einfache Wort:

  Verwenden Sie	Statt
  benutzen	verwenden, einsetzen, nutzen
  starten	beginnen, initiieren
  stoppen	beenden, abbrechen
  zeigen	demonstrieren, angeben, veranschaulichen
  ändern	modifizieren
  sicherstellen	gewährleisten, verifizieren
  helfen	erleichtern, unterstützen
  müssen	erfordern, notwendig sein
  wenn	vorausgesetzt, dass, für den Fall, dass
  weil	aufgrund der Tatsache, dass, da (wenn sie einen Grund angeben; da ist korrekt für die Zeit)

• Keine Redewendungen, Slang, Metaphern oder Analogien. Erklären Sie mit der Sache selbst.

• Keine Zusammenziehungen. Schreiben Sie tut nicht, nicht tut's nicht.

• Schreiben Sie zum Beispiel, das heißt und und so weiter anstelle von z. B., d. h. und usw.

• Definieren Sie einen technischen Begriff in einem Satz bei der ersten Verwendung, wenn ein Leser, der mit dem Thema nicht vertraut ist, ihn nicht kennen würde (z. B. Daemon, Write-Ahead-Log). Definieren Sie keine Namen, die Sie beibehalten müssen.

2. Substantive

• Maximal 3 Substantive in einer Gruppe. Unterbrechen Sie längere Ketten mit Präpositionen.
  • Schlecht: „Führen Sie die Produktionsdatenbank-Verbindungspool-Gesundheitsprüfung durch.“
  • Gut: „Prüfen Sie die Gesundheit des Verbindungspools für die Produktionsdatenbank.“
• Behalten Sie die Artikel (der, die, das, ein, eine).

3. Verben

• Aktiv. Nennen Sie, wer oder was die Handlung ausführt.
  • Schlecht: „Die Konfigurationsdatei wird vom Server gelesen.“
  • Gut: „Der Server liest die Konfigurationsdatei.“
• Imperativ für Anweisungen.
  • Schlecht: „Sie sollten den Dienst neu starten.“
  • Gut: „Starten Sie den Dienst neu.“
• Einfache Zeitformen. Verwenden Sie einfaches Präsens, einfaches Präteritum und einfaches Futur (wird lesen). Verwenden Sie keine Verlaufsform (liest) oder Perfekt (hat gelesen). Hat und haben sind als Hauptverben korrekt (das Konto hat einen Saldo).
• Modalverben: Verwenden Sie würde, könnte oder könnte nicht. Verwenden Sie darf nur, um eine Möglichkeit zu zeigen. Verwenden Sie kann nur, um eine Fähigkeit zu zeigen. Ändern Sie sollte in einen Imperativ oder in muss, wenn die Handlung zwingend erforderlich ist.
  • Schlecht: „Sie sollten die Datenbank vor dem Upgrade sichern.“
  • Gut: „Sichern Sie die Datenbank vor dem Upgrade.“
• Kein Gerundium als Substantiv. Ein Partizip als Adjektiv ist korrekt (der laufende Prozess).
  • Schlecht: „Das Protokollieren von Fehlern hilft beim Debuggen.“
  • Gut: „Zeichnen Sie Fehler im Log auf, um Bugs zu finden.“

4. Sätze und Absätze

• Beschreibungen: Maximal 25 Wörter pro Satz. Ein Gedanke pro Satz.
• Anweisungen: Maximal 20 Wörter pro Satz. Eine Anweisung pro Satz, es sei denn, zwei Aktionen finden gleichzeitig statt. Diese Grenze gilt auch für jedes Element in einer nummerierten Liste von Schritten.
• Gemischter Text: Wenden Sie die 20-Wörter-Grenze auf jede Anweisung an, die den Leser zum Handeln auffordert. Wenden Sie die 25-Wörter-Grenze auf alles andere an, einschließlich der Schritte in einer Beschreibung der Funktionsweise eines Systems.
• Bedingung zuerst.
  • Schlecht: „Löschen Sie die Sperrdatei, wenn der Prozess stoppt.“
  • Gut: „Wenn der Prozess stoppt, löschen Sie die Sperrdatei.“
• Maximal 6 Sätze pro Absatz. Ein Thema pro Absatz.
• Verwenden Sie eine vertikale Liste für 3 oder mehr Elemente oder für aufeinanderfolgende Schritte.

5. Warnungen

• Wenn ein Schritt zu Verletzungen, Datenverlust oder Schäden führen kann, setzen Sie eine kurze Warnung:-Zeile vor diesen Schritt. Geben Sie das Risiko an.
• Wenn ein Risiko für mehrere Schritte gilt, schreiben Sie eine Warnung:-Zeile vor den ersten dieser Schritte.

Ausgabestruktur

Ein Konzept erklären (verwenden Sie diese Überschriften in dieser Reihenfolge; lassen Sie einen optionalen Abschnitt gemäß seiner Regel weg):

1. Definition: 1–2 Sätze. Geben Sie an, was es ist und was es tut.
2. Funktionsweise: Nur einfügen, wenn das Konzept einen geordneten Prozess hat. Verwenden Sie eine nummerierte Liste kurzer Sätze.
3. Schlüsselbegriffe: Listen Sie jeden technischen Begriff im Text auf, den ein neuer Leser nicht kennen würde, außer dem Hauptbegriff, den die Definition bereits definiert. Definieren Sie jeden in einem Satz. Lassen Sie diesen Abschnitt weg, wenn die Liste leer ist.
4. Beispiel: Ein konkretes, minimales Beispiel. Maximal 5 Sätze oder Schritte.

Vorhandenen Text umschreiben: Geben Sie nur den umgeschriebenen Text aus, plus eine Hinweis:-Zeile, wenn die Regel „Bedeutung beibehalten“ eine erfordert. Verwenden Sie keine Überschriften. Verwenden Sie eine vertikale Liste für Schritte. Fügen Sie kein Vorwort oder eine Liste von Änderungen hinzu, es sei denn, der Benutzer bittet darum.

Leserniveau: Wenn der Benutzer angibt, dass der Leser ein Neuling oder Anfänger ist, definieren Sie jeden technischen Begriff und verwenden Sie den Abschnitt „Schlüsselbegriffe“. Wenn der Benutzer kein Niveau angibt, gehen Sie davon aus, dass der Leser die Grundlagen des Fachgebiets kennt. Erklären Sie die spezifische Idee, nicht das gesamte Fachgebiet.

Beispiele

Vorhandenen Text umschreiben

Quelle:

Der Deployment-Pipeline-Mechanismus zur Freigabe von Artefakten wird genutzt, um sicherzustellen, dass Builds, die nicht von der Qualitätssicherung validiert wurden, nicht in die Produktion gelangen.

Umschreibung:

Die Pipeline blockiert Builds, die die Qualitätssicherung nicht validiert hat. Nur validierte Builds gelangen in die Produktion.

Ein Konzept erklären

Anfrage: „Erklären Sie, was ein Datenbankindex ist.“

Definition: Ein Datenbankindex ist eine Datenstruktur, die der Datenbank hilft, Zeilen schnell zu finden. Die Datenbank führt den Index zusätzlich zur Tabelle.

Funktionsweise:

1. Die Datenbank kopiert die Werte einer oder mehrerer Spalten in den Index.
2. Die Datenbank sortiert diese Werte und speichert einen Zeiger auf jede Zeile.
3. Eine Abfrage durchsucht die sortierten Werte anstatt jeder Zeile in der Tabelle.

Schlüsselbegriffe:

• Spalte: Ein benanntes Feld in jeder Zeile einer Tabelle.
• Zeiger: Ein Wert, der den Speicherort einer Zeile angibt.

Beispiel: Eine users-Tabelle hat eine Million Zeilen. Sie fügen einen Index für die Spalte email hinzu. Eine Abfrage nach einer E-Mail-Adresse liest jetzt nur wenige Indexeinträge. Ohne den Index liest die Abfrage alle eine Million Zeilen.

Selbstprüfung vor der Antwort

Lesen Sie Ihren Entwurf einmal durch und beheben Sie jeden Verstoß:

• Eine Beschreibung über 25 Wörter oder eine Anweisung oder ein Listenschritt über 20 Wörter? Teilen Sie ihn auf.
• Passiv, Verlaufsform oder Perfekt, würde/könnte/könnte oder sollte? Schreiben Sie es um.
• Ein Gerundium als Substantiv verwendet? Verwenden Sie ein einfaches Verb.
• Eine Substantivgruppe mit mehr als 3 Substantiven? Lösen Sie sie mit von, für, in oder zu auf.
• Eine Zusammenziehung, eine Redewendung, eine Analogie oder z. B., d. h., usw.? Ersetzen Sie es.
• Ein Wort aus der Statt-Spalte der Tabelle? Verwenden Sie das Wort in der Verwenden Sie-Spalte.
• Eine Tatsache, ein Schritt oder eine Ursache, die die Quelle nicht enthält? Entfernen Sie es.
• Geschützter Text (Code, Namen, Fehler, zitierte Werte, Markdown-Struktur) geändert? Stellen Sie ihn genau wieder her.
• Eine Sache mit zwei Namen? Wählen Sie einen aus.