Kurze Hilfeseiten schreiben, die die häufigsten Beispiele eines Befehls zeigen

## Nach einer vorhandenen Seite suchen und den Ordner passend zum System wählen Durchsuchen Sie vor jeder Neuerstellung sämtliche ursprünglichen und übersetzten Seitenbäume nach dem Befehl. Ist bereits eine Seite vorhanden, bearbeiten Sie diese, anstatt ein Duplikat anzulegen. Ist keine vorhanden, ermitteln Sie, wo die dokumentierte Syntax tatsächlich funktioniert. - Legen Sie einen Befehl nur dann im gemeinsamen Verzeichnis ab, wenn dieselbe Syntax auf mindestens zwei Plattformen funktioniert. - Legen Sie einen Befehl, der auf einer einzigen Plattform funktioniert, im Verzeichnis dieser Plattform ab. - Belassen Sie englische Seiten im primären Seitenbaum und Übersetzungen in sprachspezifischen Bäumen mit demselben Plattformpfad. - Verwenden Sie Dateinamen in Kleinbuchstaben, sofern keine plattformspezifische Richtlinie die verbindliche Groß- und Kleinschreibung des Befehls im Seitentitel oder beim Aufruf verlangt. Wählen Sie ein Verzeichnis nicht aufgrund des Bekanntheitsgrads oder Namens eines Befehls. Prüfen Sie zuerst seine unterstützten Plattformen und seine Syntax. ## Die Seite kurz halten und Titel und Beschreibung vor die Beispiele stellen Verfassen Sie jede Seite als kleine Markdown-Referenz in dieser festen Reihenfolge: 1. Genau eine H1-Überschrift, deren Befehlsname mit dem Dateinamen übereinstimmt; die Groß- und Kleinschreibung darf nur dort unberücksichtigt bleiben, wo das Repository dies erlaubt. 2. Eine Beschreibung als Zitatblock, vorzugsweise ein- oder zweizeilig. 3. Eine verpflichtende Zeile „Weitere Informationen“ mit einer in Winkelklammern gesetzten URL der Originalquelle. 4. Praxisnahe Beispiele, jeweils mit einer stichpunktartigen Beschreibung im Imperativ und anschließend einer eigenen Befehlszeile als eingebetteter Code. 5. Einen abschließenden Zeilenumbruch am Dateiende. Verwenden Sie standardmäßig fünf Beispiele und niemals mehr als acht. Lassen Sie zwischen Beschreibung und Befehl sowie zwischen den Beispielen jeweils eine Leerzeile. Verwenden Sie im Seiteninhalt weder Fettdruck noch Kursivschrift oder schmückende Markdown-Formatierung. ## Beispiele für die häufigsten echten Aufgaben auswählen Wählen Sie Beispiele, die die häufigsten praktischen Aufgaben lösen. Formulieren Sie Beschreibungen im Imperativ: „Dateien auflisten“, nicht „Listet Dateien auf“. Halten Sie sie kurz und handlungsorientiert und erläutern Sie keine allgemeinen Betriebssystemkonzepte. Prüfen Sie jedes Beispiel anhand des Befehlshandbuchs, der eingebauten Hilfe oder der offiziellen Dokumentation. Behalten Sie den dokumentierten Abstand zwischen Optionen und Argumenten bei; verwenden Sie `--option arg`, sofern der Befehl nicht ausdrücklich eine andere Form verlangt. Setzen Sie „Hilfe anzeigen“ und „Version anzeigen“ in dieser Reihenfolge als die letzten beiden Beispiele ein, wenn diese Aufrufe vorhanden sind. Sie haben eine geringere Priorität. Lassen Sie daher eines davon weg, wenn ein nützlicheres Praxisbeispiel benötigt wird und sonst die Seitengrenze überschritten würde. ## Zu ersetzende Stellen mit doppelten geschweiften Klammern markieren Schließen Sie ersetzbare Werte in doppelte geschweifte Klammern ein. Verwenden Sie die folgenden semantischen Platzhalterformen einheitlich: - `{{path/to/file}}`, `{{path/to/directory}}` und `{{filename}}` für Dateisystemeingaben; - `{{file1 file2 ...}}` für mehrere Argumente; - `{{option1|option2}}` für Alternativen; - `{{1..5}}` für Zahlenbereiche und `{{*.ext}}` für Platzhaltermuster; - `{{[-v|--verbose]}}` für gleichwertige Kurz- und Langoptionen; - `{{[-it|--interactive --tty]}}` für zusammengehörige Schalter. Zeigen Sie sowohl die Kurz- als auch die Langform, wenn beide vorhanden sind. Erfinden Sie niemals eine Kurzform: Versionsschalter und andere gebräuchliche Optionen unterscheiden sich je nach Befehl. Verschachteln Sie keine Platzhalter und ersetzen Sie die vorgeschriebene Syntax mit doppelten geschweiften Klammern weder durch einzelne geschweifte Klammern noch durch eckige Klammern. Verwenden Sie Winkelklammern für Tastenanschläge: `<a>`, `<Enter>`, `<Space>`, `<Ctrl>`, `<Alt>` und `<Shift>`. Schreiben Sie Kombinationen mit einem Leerzeichen, etwa `<Ctrl c>`, und Folgen als unmittelbar benachbarte Gruppen, etwa `<Esc><u>`. ## Erst prüfen, ob der Link funktioniert, dann auf das offizielle Handbuch verweisen Jede Seite muss auf weiterführende Informationen verweisen. Bevorzugen Sie das offizielle Handbuch des Befehls, die Projektdokumentation, einen gepflegten Handbuchseitendienst oder die Dokumentation des Plattformanbieters. Folgen Sie vor der Annahme eines Verweises allen Weiterleitungen und bestätigen Sie, dass die abschließende Antwort erfolgreich ist. Verlassen Sie sich nicht auf eine URL, die lediglich plausibel aussieht. Belassen Sie den Verweis in Winkelklammern in der eigenen Zeile „Weitere Informationen“ und vermeiden Sie werbliche oder inoffizielle Quellen, wenn eine Primärquelle verfügbar ist. Nutzen Sie dieselben maßgeblichen Quellen, um Befehlsnamen, Optionsformen, Argumentabstände, Plattformverhalten sowie Hilfe- und Versionssyntax zu bestätigen. ## Pfade und Variablen so schreiben, wie Windows und andere Systeme es erwarten Verwenden Sie auf Windows-Befehlsseiten Dateinamen in Kleinbuchstaben, sofern die Repository-Richtlinie nichts anderes vorgibt. Behalten Sie jedoch die verbindliche Groß- und Kleinschreibung des Befehls in der H1-Überschrift und in den Beispielen bei. Verwenden Sie in Pfadplatzhaltern umgekehrte Schrägstriche. Schreiben Sie Umgebungsvariablen in der Syntax der dokumentierten Befehlsumgebung: `%VARIABLE%` für den herkömmlichen Befehlszeileninterpreter und `$Env:VARIABLE` für PowerShell. Für PowerShell vorgesehene Beispiele müssen sowohl in der ältesten unterstützten als auch in der aktuellen Ausgabe funktionieren, sofern die Seite keine engere Anforderung festlegt. Befolgen Sie auf anderen Plattformen deren eigene Pfad-, Befehlsumgebungs-, Umgebungsvariablen- und Optionskonventionen. Eine gemeinsame Seite ist nur gültig, wenn die gezeigte Befehlssyntax tatsächlich übertragbar ist. ## Eigene Seiten für andere Namen und Unterbefehle eines Befehls anlegen Erstellen Sie Alias-Seiten mit dem Alias-Hilfsprogramm des Repositories, sofern eines vorhanden ist. Erklären Sie, dass der Befehl ein Alias ist, verweisen Sie auf die Informationen der Originalquelle und geben Sie ein Beispiel an, das die Referenzseite des ursprünglichen Befehls öffnet. Halten Sie übersetzte Alias-Seiten mit demselben Hilfsprogramm synchron, anstatt deren erzeugte Struktur unabhängig zu bearbeiten. Erwähnen Sie bei Befehlen mit Unterbefehlen in der Beschreibung der übergeordneten Seite repräsentative Unterbefehle, wenn diese eigene Seiten besitzen. Geben Sie jedem dokumentierten Unterbefehl eine eigene Seite mit Bindestrichen im Namen und fügen Sie ein Beispiel ein, das die zugehörige Unterbefehlsreferenz öffnet. Überladen Sie die übergeordnete Seite nicht mit ausführlichen Unterbefehlsabläufen, die auf eigene Seiten gehören. ## Die Seite übersetzen, ohne Befehle und Aufbau zu ändern Übersetzen Sie erst, nachdem die englische Seite vorhanden ist. Behalten Sie Beispielstruktur, Plattformpfad, Befehle und Platzhalter unverändert bei. Ändern Sie reservierte Beispieldomänen nicht und belassen Sie Wörter in Platzhaltern in der Ausgangssprache, wenn die Repository-Richtlinie dies verlangt. Wenden Sie sprachraumspezifische Schreibregeln an, anstatt die englische Grammatik mechanisch zu übernehmen. Zum Beispiel: - Im Chinesischen werden lateinische Schrift und Zahlen durch Leerzeichen vom chinesischen Text getrennt und vollbreite Satzzeichen verwendet. - Im Französischen stehen Beispielbeschreibungen in der dritten Person, und vor Satzzeichen, die dies verlangen, steht ein Leerzeichen. - Im Spanischen werden Beschreibungen in der dritten Person und bevorzugte lokalisierte Fachbegriffe verwendet. - Im brasilianischen und europäischen Portugiesisch stehen Beschreibungen in der dritten Person. - Im Indonesischen wird eine prägnante Befehlsbeschreibungsform ohne unnötige Verbpräfixe verwendet. Prüfen Sie die übersetzte Seite mit denselben Strukturprüfungen wie die englische Quelle. ## Die Seite mit dem Prüfprogramm prüfen, bevor ein Mensch sie durchsieht Führen Sie vor der Bitte um menschliche Begutachtung das Seitenprüfprogramm des Repositories für die geänderte Datei aus. Prüfen Sie den gesamten Seitenbaum nur, wenn die Änderung oder die Repository-Richtlinie dies verlangt. Begutachten Sie die Seite hinsichtlich folgender Punkte: - Titel und Dateiname stimmen überein; - die Beschreibung im Zitatblock ist kurz und enthält einen gültigen Informationsverweis; - es gibt fünf bevorzugte und höchstens acht Beispiele; - die Beschreibungen stehen im Imperativ und die Leerzeilen sind korrekt; - die Optionsformen sind verifiziert und Platzhalter verwenden doppelte geschweifte Klammern; - Plattformverzeichnis und plattformeigene Syntax sind korrekt; - Hilfe- und Versionsbeispiele stehen, sofern vorhanden, an den letzten Positionen; - es gibt keine schmückende Formatierung; - Übersetzungen halten die sprachraumspezifischen Regeln ein; - am Dateiende steht ein Zeilenumbruch. Verwenden Sie, sofern vorhanden, die Wartungsskripte des Repositories für mechanische Aktualisierungen von Titeln, Verweisen, Aliassen, Querverweisen und Befehlen. Bevorzugen Sie vor einer umfassenden skriptgestützten Änderung den `dry-run`-Modus. ## Der KI vor dem Schreiben das Handbuch und ähnliche Seiten geben Senken Sie die KI-Kosten und die Zahl der Korrekturschleifen, indem Sie vor der Erstellung Nachweise bereitstellen. Fügen Sie die Hilfe- oder Handbuchausgabe des Befehls bei, verweisen Sie auf zwei oder drei ähnliche, freigegebene Seiten und stellen Sie die Seitenvorlage bereit, anstatt vom Agenten das Erinnern der Konventionen zu verlangen. Prüfen Sie zuerst, ob bereits eine Seite vorhanden ist. Bündeln Sie Anfragen zu verwandten Seiten, wenn sie denselben Kontext nutzen, begutachten Sie jedoch jede Seite einzeln. Erstellen Sie fünf oder sechs besonders nützliche Beispiele, anstatt die Obergrenze von acht Beispielen auszuschöpfen. Führen Sie das Prüfprogramm vor der menschlichen Begutachtung aus, damit Formatierungsfehler keine Aufmerksamkeit der prüfenden Person beanspruchen. Einsparungen müssen aus besseren Eingaben, Wiederverwendung und deterministischer Prüfung entstehen, niemals aus dem Auslassen der Quellenprüfung oder einer Minderung der Seitenqualität.