Technischer Artikel

Anleitung für KI-Agenten zum Erstellen, Überarbeiten und Prüfen technischer Artikel mit formaler Sprache, kohärenter Struktur, präziser Terminologie, praktischen Beispielen und überprüfbaren Referenzen.

1. Vorteile
2. Prinzipien
- 2.1. Sprache
- 2.2. Inhaltsintegrität
3. Struktur
4. Arbeitsablauf
5. Styleguide
6. Qualitätstoren
7. Ressourcen
8. Referenzen

1. Vorteile

Konsistenz

Eine stabile Artikelgrammatik macht technische Inhalte themenübergreifend vorhersagbar und ermöglicht es Lesern, Definitionen, Kategorien, Prinzipien, Beispiele und Referenzen zu finden, ohne die Dokumentstruktur neu erlernen zu müssen.
Lesbarkeit

Präzise Definitionsabsätze, explizite Überschriften und Begriff-Definitions-Listen reduzieren die kognitive Belastung, während die technische Präzision erhalten bleibt.
Navigierbarkeit

Ein manuell gepflegtes hierarchisches Inhaltsverzeichnis und nummerierte Überschriften legen die konzeptionelle Hierarchie offen und bieten eine direkte Navigation für lange Artikel.
Wiederverwendbarkeit

Taxonomien, Terminologielisten, praktische Beispiele und qualifizierte Referenzen machen jeden Artikel sowohl als Einführung als auch als langlebige technische Referenz nützlich.
Überprüfbarkeit

Deterministische Formatierungs- und Beweisregeln ermöglichen es Prüfern, strukturelle Mängel, Sprachmängel und technische Ungenauigkeiten zu trennen.

2. Prinzipien

2.1. Sprache

Formal

Verwenden Sie neutrales Englisch, das für Softwareentwickler, Systemingenieure, Sicherheitsexperten und technische Entscheidungsträger geeignet ist.
Enzyklopädisch

Definieren Sie das Thema, bevor Sie Praktiken vorschreiben. Erklären Sie, was ein Konzept ist, wie es kategorisiert wird und wo es angewendet wird, bevor Sie Empfehlungen präsentieren.
Präzise

Bevorzugen Sie domänenspezifische Nomen und Verben gegenüber breiten oder werblichen Formulierungen. Unterscheiden Sie Standards, Spezifikationen, Protokolle, Werkzeuge, Frameworks, Praktiken, Metriken und Architekturmuster.
Unpersönlich

Bevorzugen Sie die dritte Person oder unpersönliche Konstruktionen. Vermeiden Sie Ich-Erzählung, direkte Ansprache in der zweiten Person, rhetorische Fragen und gesprächige Füllwörter.
Deklarativ

Geben Sie Definitionen, Beziehungen, Einschränkungen und Ergebnisse direkt an. Verwenden Sie modale Verben nur, wenn eine tatsächliche Anforderung, Empfehlung, Möglichkeit oder Unsicherheit ausgedrückt wird.

2.2. Inhaltsintegrität

Belege

Untermauern Sie extern überprüfbare Behauptungen mit autoritativen Quellen. Bevorzugen Sie Normungsgremien, offizielle Dokumentationen, Primärforschung und kanonische Repositorys.
Aktualität

Überprüfen Sie zeitkritische Fakten, versionsspezifisches Verhalten, Leistungsschwellen, gesetzliche Anforderungen und Produktfunktionen, bevor Sie sie aufnehmen.
Umfang

Konzentrieren Sie jeden Artikel auf ein technisches Thema. Verlinken Sie zu benachbarten Artikeln, anstatt wesentliches Hintergrundmaterial zu duplizieren.
Taxonomische Kohärenz

Gruppieren Sie Konzepte nach einer expliziten Klassifikationsdimension auf einmal. Mischen Sie Werkzeuge, Praktiken, Ergebnisse und Eigenschaften nicht als gleichrangig, es sei denn, der Abschnitt erklärt die Beziehung.
Beispiele

Verwenden Sie Beispiele, die syntaktisch gültig, technisch plausibel und direkt mit der vorhergehenden Erklärung verbunden sind.

3. Struktur

3.1. Datei und Titel

Dateiname

Verwenden Sie einen Kleinbuchstaben-Kebab-Case-Dateinamen, der das Thema identifiziert, z. B. technical-debt.md, feature-flags.md oder file-systems.md.
Frontmatter

Fügen Sie Artikeldaten kein YAML-Frontmatter hinzu, es sei denn, das Zielrepository verlangt dies explizit.
H1-Titel

Beginnen Sie mit genau einer H1-Überschrift, die den kanonischen Themennamen im Titel-Case enthält.
```
# Feature Flags
```

3.2. Einleitung

Setzen Sie einen oder zwei prägnante Absätze unmittelbar nach der H1-Überschrift.

Definition

Definieren Sie das Thema im ersten Satz. Schreiben Sie ein Akronym beim ersten Vorkommen aus, wenn es im Kontext des Artikels nicht allgemein selbsterklärend ist.
Kontext

Erklären Sie den Zweck, die operative Rolle oder die Beziehung des Themas zur Softwareentwicklung. Führen Sie vor dem Inhaltsverzeichnis keine detaillierte Taxonomie ein.

Beispiel:

# Feature Flags

Feature Flags sind Laufzeitsteuerungen, die Anwendungsverhalten aktivieren oder deaktivieren, ohne dass eine neue Bereitstellung erforderlich ist. Sie entkoppeln die Codebereitstellung von der Feature-Freigabe und unterstützen kontrollierte Rollouts, Experimente und operative Schadensbegrenzung.

3.3. Inhaltsverzeichnis

Fügen Sie ein manuell gepflegtes Markdown-Inhaltsverzeichnis nach der Einleitung und vor dem ersten H2-Abschnitt ein.

Hierarchie

Spiegeln Sie jede nummerierte H2-, H3- und relevante H4-Überschrift mit einer Einrückung von zwei Leerzeichen pro Ebene wider.
Beschriftungen

Geben Sie das vollständige numerische Präfix und den Überschriftentext an.
Anker

Verwenden Sie GitHub-kompatible Kleinbuchstaben-Anker. Entfernen Sie Satzzeichen gemäß den GitHub-Überschriftregeln, während Sie Bindestriche zwischen Wörtern beibehalten.
Vollständigkeit

Fügen Sie Einträge im Inhaltsverzeichnis hinzu, entfernen Sie sie oder benennen Sie sie um, wenn sich Überschriften ändern.

Beispiel:

- [1. Kategorie](#1-kategorie)
  - [1.1. Bereitstellungsstrategien](#11-bereitstellungsstrategien)
    - [1.1.1. Blue-Green-Bereitstellung](#111-blue-green-bereitstellung)
    - [1.1.2. Canary-Bereitstellung](#112-canary-bereitstellung)
- [2. Prinzip](#2-prinzip)
- [3. Best Practice](#3-best-practice)
- [4. Terminologie](#4-terminologie)
- [5. Referenzen](#5-referenzen)

3.4. Nummerierte Abschnitte

Verwenden Sie in jeder Artikelüberschrift unter H1 eine arabische Dezimalnummerierung.

H2

Verwenden Sie ## 1. <Abschnitt> für Abschnitte der obersten Ebene.
H3

Verwenden Sie ### 1.1. <Unterabschnitt> für Abschnitte der zweiten Ebene.
H4

Verwenden Sie #### 1.1.1. <Thema> nur, wenn ein Unterabschnitt eine umfangreiche Taxonomie enthält, die eine weitere Ebene erfordert.
Tiefe

Bevorzugen Sie nicht mehr als vier Überschriftsebenen einschließlich H1. Ersetzen Sie übermäßige Überschriftentiefe durch Begriff-Definitions-Listen oder Tabellen.
Kanonische Abschnitte

Wählen Sie nur Abschnitte aus, die zum Thema beitragen. Übliche korpuskompatible Bezeichnungen umfassen Vorteile, Kategorie, Prinzip, Prinzipien, Best Practice, Terminologie und Referenzen.
Reihenfolge

Beginnen Sie mit grundlegenden Konzepten und Kategorien, fahren Sie mit Prinzipien oder Praktiken fort und schließen Sie mit Terminologie und Referenzen ab.

3.5. Taxonomien und Definitionen

Verwenden Sie Prosa für konzeptionelle Übergänge und Begriff-Definitions-Listen für scannbare technische Inhalte.

Abschnittseinleitung

Eröffnen Sie einen Hauptabschnitt mit einem oder zwei Absätzen, die die Klassifikationsdimension oder den Zweck des Abschnitts erläutern.

Begriff-Definitions-Muster

Präsentieren Sie ein technisches Label als Aufzählungspunkt und seine Erklärung als eingerücktes Blockzitat.

- Atomarität
  > Atomarität stellt sicher, dass eine Transaktion als eine Einheit abgeschlossen oder zurückgerollt wird, ohne ein Teilergebnis zu behalten.

Gruppiertes Muster

Verwenden Sie ein Element einer geordneten Liste als lokale Gruppenüberschrift, wenn ein Unterabschnitt mehrere unterschiedliche Ansichten enthält, wie z. B. Konventionen, Beispiele oder Werkzeuge.
Großschreibung von Bezeichnungen

Verwenden Sie Titel-Case für konzeptionelle Bezeichnungen und Satz-Case für Beschreibungen.
Beschreibungsqualität

Beginnen Sie Beschreibungen mit der Rolle, dem Verhalten oder der definierenden Eigenschaft des Begriffs. Vermeiden Sie zirkuläre Definitionen, die das Label wiederholen, ohne Bedeutung hinzuzufügen.

3.6. Beispiele und Daten

Eigenständige Beispiele

Führen Sie eigenständige Beispiele auf Prosaebene mit Beispiel: ein. Verwenden Sie in gruppierten Unterabschnitten wie Beispiele und Erklärungen stattdessen eine beschreibende Beispielbezeichnung.
Codebeispiele

Verwenden Sie einen Codeblock mit dem genauesten Sprachbezeichner.
Inline-Syntax

Verwenden Sie Backticks für Befehle, Dateipfade, Konfigurationsschlüssel, Bezeichner, Literale und kurze Syntaxfragmente.
Tabellen

Verwenden Sie Markdown-Tabellen für kompakte Vergleiche, Matrizen, Metriken, Befehle oder aufgezählte Referenzdaten. Halten Sie den Zelleninhalt parallel und vermeiden Sie Prosatext in Zellen.
Diagramme

Verwenden Sie textbasierte Diagramme wie Mermaid, wenn Beziehungen oder Abläufe nicht effizient mit Prosa oder einer Tabelle erklärt werden können.
Hinweise

Verwenden Sie GitHub-Hinweise sparsam für Einschränkungen, Vorbehalte, Querverweise oder Informationen, die die Interpretation wesentlich ändern.
```
> [!HINWEIS]
> Der Metrik-Schwellenwert hängt vom zitierten Berichtszeitraum ab und muss vor der Veröffentlichung überprüft werden.
```

3.7. Referenzen

Beenden Sie jeden Artikel mit einem nummerierten Abschnitt Referenzen.

Interne Referenzen

Verwenden Sie repository-relative Links für verwandte Sentenz-Artikel.
```
- Sentenz-Artikel [Versionierung](../articles/versioning.md).
```

Externe Referenzen

Nennen Sie die Organisation oder den Herausgeber vor dem verlinkten Titel und identifizieren Sie den Quelltyp nach dem Link.

- NIST-Veröffentlichung [Secure Software Development Framework (SSDF) Version 1.1](https://csrc.nist.gov/pubs/sp/800/218/final).
- Kubernetes-Dokumentation [Dokumentation](https://kubernetes.io/docs/).
- GitHub-Repository [DORA Four Keys](https://github.com/dora-team/fourkeys).

Quelltypen

Verwenden Sie ein präzises Qualifikationsmerkmal wie Artikel, Dokumentation, Seite, Veröffentlichung, Repository, Bericht, Spezifikation oder Standard.
Relevanz

Fügen Sie nur Quellen ein, die im Artikel zitiert oder wesentlich verwendet werden. Erstellen Sie keine allgemeine Leseliste, die nichts mit den Behauptungen des Artikels zu tun hat.

4. Arbeitsablauf

4.1. Erstellen

Untersuchen

Lesen Sie benachbarte Dateien im Zielartikelverzeichnis. Notieren Sie das lokale Überschriftenvokabular, den Linkstil, Code-Block-Konventionen und verwandte interne Artikel.
Umfang

Definieren Sie das Artikelthema, die beabsichtigte Tiefe und die primäre Klassifikationsdimension. Trennen Sie benachbarte Themen in verlinkte Artikel.
Recherchieren

Sammeln Sie autoritative Primärquellen. Überprüfen Sie Terminologie, Standards, Metriken, Produktverhalten und zeitkritische Details.
Gliedern

Wählen Sie die erforderlichen kanonischen Abschnitte aus und erstellen Sie eine nummerierte Überschriftenhierarchie, bevor Sie Prosa verfassen.
Vorlage laden

Laden Sie assets/technical-article-template.md beim Erstellen eines neuen Artikels. Entfernen Sie Abschnitte, die nicht zum Thema beitragen.
Einleitung entwerfen

Schreiben Sie den H1-Titel und einen oder zwei Definitionsabsätze. Legen Sie das Thema und den technischen Kontext fest, ohne Implementierungsdetails vorwegzunehmen.
Inhaltsverzeichnis erstellen

Spiegeln Sie die geplante Überschriftenhierarchie wider und generieren Sie genaue GitHub-kompatible Anker.
Abschnitte schreiben

Fügen Sie Abschnittseinleitungen, Begriff-Definitions-Listen, Beispiele, Tabellen, Diagramme und Hinweise nur dort hinzu, wo sie das Verständnis verbessern.
Referenzen hinzufügen

Fügen Sie interne relative Links und externe quellqualifizierte Referenzen hinzu. Stellen Sie sicher, dass jede wesentliche externe Behauptung eine angemessene autoritative Quelle hat.
Validieren

Wenden Sie alle Qualitätstoren an, bevor Sie den Artikel zurückgeben oder committen.

4.2. Überarbeiten

Absicht bewahren

Identifizieren Sie das Thema, den Umfang und die Taxonomie des vorhandenen Artikels, bevor Sie die Struktur ändern.
Vorlage laden

Laden Sie assets/technical-article-template.md vor der Überarbeitung des Artikels. Verwenden Sie es als strukturelle Grundlage, entfernen Sie nicht zutreffende Vorlagenabschnitte und bewahren Sie gültige artikelspezifische Abschnitte.
Diagnostizieren

Trennen Sie Mängel in technische Genauigkeit, Taxonomie, Organisation, Sprache, Formatierung, Links, Beispiele und Referenzen.
Normalisieren

Gleichen Sie Titel, Einleitung, Inhaltsverzeichnis, Nummerierung, Überschriftsebenen, Listen, Blockzitate, Code-Blöcke und Referenzen mit dieser Anleitung ab.
Sprache verfeinern

Ersetzen Sie vage, sich wiederholende, gesprächige oder werbliche Formulierungen durch direkte technische Definitionen und domänenangemessene Verben.
Navigation abgleichen

Aktualisieren Sie Anker, Querverweise und Referenzen nach jeder Änderung von Überschriften oder Dateinamen.
Validieren

Führen Sie alle Qualitätstoren erneut aus und bestätigen Sie, dass die Überarbeitung keine technisch relevanten Informationen ohne expliziten Grund entfernt.

4.3. Prüfen

Vorlage laden

Laden Sie assets/technical-article-template.md vor der Prüfung eines Artikels. Verwenden Sie es als strukturelle Grundlage und melden Sie weggelassene optionale Abschnitte nicht als Mängel, es sei denn, ihr Fehlen erzeugt ein Vollständigkeits- oder Kohärenzproblem.
Bewerten

Prüfen Sie den Artikel in der folgenden Reihenfolge:
1. Technische Korrektheit
2. Umfang und taxonomische Kohärenz
3. Strukturelle Konformität
4. Terminologie und Akronyme
5. Beispiele, Tabellen und Diagramme
6. Links und Referenzen
7. Grammatik, Zeichensetzung und Lesbarkeit
Ergebnisse melden

Melden Sie Ergebnisse mit der betroffenen Überschrift oder Zeile, dem Mangel, seiner technischen Konsequenz und einer konkreten Korrektur. Priorisieren Sie sachliche Fehler und strukturelle Inkonsistenzen gegenüber stilistischen Präferenzen.

5. Styleguide

5.1. Stimme und Ton

Präsens

Verwenden Sie Präsens für Definitionen, Fähigkeiten und aktuelle Praktiken.
Vergangenheit

Verwenden Sie Vergangenheit nur für historische Ereignisse oder überholtes Verhalten.
Aktiv

Bevorzugen Sie das Aktiv, wenn der Akteur oder Mechanismus wichtig ist.
Passiv

Verwenden Sie das Passiv, wenn der Prozess oder das Ergebnis im Fokus steht und der Akteur irrelevant ist.
Unpersönliche Perspektive

Vermeiden Sie Pronomen der ersten und zweiten Person.
Fachjargon

Definieren Sie jeden domänenspezifischen Begriff beim ersten Gebrauch, es sei denn, er ist im Kontext des Artikels allgemein bekannt.
Modale Verben

Verwenden Sie muss, wenn eine Anforderung von einer externen Autorität durchgesetzt wird. Verwenden Sie sollte für eine empfohlene Vorgehensweise und kann für eine zulässige Option oder eine beobachtbare Eigenschaft. Reservieren Sie darf für verbotene Handlungen.

5.2. Terminologie

Fachbegriffe

Bevorzugen Sie branchenübliche Begriffe gegenüber Markennamen, es sei denn, der Artikel behandelt explizit ein herstellerspezifisches Werkzeug oder Protokoll.
Akronyme

Schreiben Sie ein Akronym beim ersten Vorkommen in einem Artikel aus, es sei denn, es ist in der Zielgruppe des Artikels universell verständlich.
Neologismen

Vermeiden Sie neu geprägte Begriffe, es sei denn, sie sind in der technischen Literatur gut etabliert.
Synonyme

Verwenden Sie für dasselbe Konzept in einem Artikel einen Begriff. Führen Sie alternative Begriffe als sekundäre Verweise an derselben Stelle ein, an der der primäre Begriff definiert wird.

5.3. Sätze und Absätze

Satzlänge

Variieren Sie die Satzlänge, um Monotonie zu vermeiden, aber bevorzugen Sie einen, zwei oder drei Sätze pro Absatz. Teilen Sie Sätze mit mehr als 40 Wörtern auf.
Absatzaufbau

Beginnen Sie einen Absatz mit dem Hauptgedanken; erweitern Sie ihn mit Details oder Beweisen; schließen Sie ihn, indem Sie ihn mit dem nächsten Punkt verbinden.
Parallele Struktur

Verwenden Sie in Aufzählungen, Überschriften und Tabellenspalten innerhalb derselben Gruppe parallele grammatikalische Formen.
Aufzählungszeichen

Verwenden Sie Aufzählungszeichen nur für nicht geordnete Sammlungen. Verwenden Sie für sequenzielle Schritte, Rangfolgen oder abgestufte Kriterien nummerierte Listen.
Übergänge

Leiten Sie Absätze mit Übergangsphrasen ein, wenn Sie zwischen verschiedenen Kategorien, Zeiträumen oder Analyseebenen wechseln.

5.4. Listen und Blockzitate

Formatierung von Aufzählungslisten

Verwenden Sie - für Aufzählungspunkte. Schreiben Sie den ersten Buchstaben jedes Aufzählungspunktes groß, wenn er ein vollständiger Satz ist; verwenden Sie Kleinbuchstaben, wenn er einen Satz fortsetzt.
Formatierung von nummerierten Listen

Nummerieren Sie alle Elemente in einer geordneten Liste mit 1., damit das Rendern automatisch erfolgt. Verwenden Sie bei externen Verweisen auf Listennummern explizite Zahlen.
Blockzitate

Verwenden Sie Blockzitate (> ) nur für wörtliche Zitate, Definitionen oder Text, der vom Hauptfluss getrennt werden muss.
Verschachtelung

Verschachteln Sie nicht mehr als zwei Ebenen von Listen oder mehr als eine Ebene von Blockzitaten.

5.5. Links und Zitate

Linktext

Verwenden Sie als Linktext den Seitentitel, wenn Sie auf eine andere Seite verlinken. Wenn der Linktext kein Titel ist, schreiben Sie ihn in Satz-Case.
Externe Links

Öffnen Sie externe Links in einem relativen Kontext. Fügen Sie nach dem schließenden Klammerausdruck des Links ein Leerzeichen und den Quelltyp ein.
Zitate

Verwenden Sie Anführungszeichen für direkte Zitate, nicht für Betonung. Reservieren Sie einfache Anführungszeichen für Zitate innerhalb von Zitaten.

5.6. Code, Tabellen und Hinweise

Codeblöcke

Verwenden Sie Codeblöcke mit einem Sprachbezeichner für mehrzeilige Code- und Konfigurationsbeispiele. Verwenden Sie Backticks für kurze Inline-Referenzen.
Tabellenformat

Richten Sie Tabellen mit --- linksbündig aus, es sei denn, Zahlen erfordern eine rechtsbündige Ausrichtung. Verwenden Sie eine einzelne Kopfzeile; verschmelzen Sie Zellen oder Überschriften nicht mit HTML.
GitHub-Hinweise

Verwenden Sie > [!HINWEIS], > [!WICHTIG] und > [!WARNUNG], wenn der Inhalt nicht in den Hauptabsatz passt. Stellen Sie jedem Hinweis einen Absatz mit Kontext voran.

6. Qualitätstoren

Technische Korrektheit: Alle Fakten sind überprüft und korrekt.
Taxonomie: Konzepte sind nach einer singulären expliziten Dimension gruppiert.
Struktur: Nummerierte Überschriften, ein manuelles Inhaltsverzeichnis und kanonische Abschnitte sind vorhanden.
Sprache: Die Grammatik ist formal, enzyklopädisch, unpersönlich und deklarativ.
Format: Codeblöcke, Tabellen und Hinweise haben die korrekte Syntax.
Beispiele: Alle Beispiele sind syntaktisch gültig und technisch plausibel.
Links: Interne und externe Links sind gültig und korrekt qualifiziert.
Referenzen: Jede wesentliche Behauptung wird durch eine autoritative Quelle gestützt.
Lesbarkeit: Prosa ist prägnant; Absätze sind kurz.

7. Ressourcen

8. Referenzen

Sentenz Technischer Artikel Gute-Laune-Artikel
Sentenz Wissensmanagement
Markdown GitHub Flavored Markdown Spec Spezifikation
Mermaid Mermaid-Dokumentation Dokumentation

sentenz/technical-article

Was ist technical-article?

In Ihrer bevorzugten KI fragen

Dokumentation