Einstieg in die Mitwirkung an PowerShell-Dokumentation

Dieser Artikel bietet einen Überblick über die ersten Schritte als Mitwirkender an der PowerShell-Dokumentation.

Struktur von „PowerShell-Docs“

Es gibt drei Kategorien von Inhalten im PowerShell-Docs Repository:

• Referenzinhalt
• Konzeptionelle Inhalte
• Metadaten- und Konfigurationsdateien

Referenzinhalt

Der Referenzinhalt ist die PowerShell-Cmdlet-Referenz für die Cmdlets von PowerShell. Die Cmdlet-Referenz wird in Versionsordnern (z. B. 5.1, 7.4, 7.5 und 7.6) gesammelt, die den Verweis für die Module enthalten, die mit PowerShell ausgeliefert werden. Dieser Inhalt dient auch zum Erstellen der vom Cmdlet Get-Help angezeigten Hilfeinformationen.

Konzeptioneller Inhalt

Die konzeptionelle Dokumentation ist nicht nach Version organisiert. Alle Artikel werden für jede Version von PowerShell angezeigt.

Anmerkung

Wenn ein konzeptioneller Artikel hinzugefügt, entfernt oder umbenannt wird, muss das Inhaltsverzeichnis aktualisiert werden. Alle gelöschten oder umbenannten Dateien müssen umgeleitet werden.

Metadatendateien

Dieses Projekt enthält mehrere Arten von Metadatendateien. Die Metadatendateien steuern das Verhalten unserer Buildtools und des Veröffentlichungssystems. Nur PowerShell-Docs-Maintainer und genehmigte Mitwirkende dürfen diese Dateien ändern. Wenn Sie der Meinung sind, dass eine Metadatei geändert werden soll, öffnen Sie ein Problem, um die erforderlichen Änderungen zu besprechen.

Metadateien im Root des Repositorys

• .* – Konfigurationsdateien im Stammverzeichnis des Repositorys
• *.md – Projektdokumentation im Root des Repositorys
• *.yml – Projektdokumentation im Root des Repositorys
• .devcontainer/* – Devcontainer-Konfigurationsdateien
• .github/**/* – GitHub-Vorlagen, Aktionen und andere Metadateien
• .vscode/**/* – Konfigurationen der VS Code-Erweiterung
• assets/* - enthält herunterladbare Dateien, die in der Dokumentation verknüpft sind
• redir/* – enthalten Zuordnungsdateien für die Umleitung
• tests/* – Testtools, die vom Buildsystem verwendet werden
• tools/* – andere Tools, die vom Buildsystem verwendet werden

Metadateien in der Dokumentationssammlung

• reference/**/*.json – docset-Konfigurationsdateien
• reference/**/*.yml – TOC und andere strukturierte Inhaltsdateien
• reference/bread/* – Konfiguration der Breadcrumb-Navigation
• reference/includes/* – Markdown-Include-Dateien
• reference/mapping/* – Konfiguration der Versionsverwaltung
• reference/**/media/** – in der Dokumentation verwendete Bilddateien
• reference/module/* – Konfiguration der Modul-Browser-Seite

Erstellen neuer Artikel

Ein GitHub-Issue muss für jedes neue Dokument erstellt werden, das Sie einreichen möchten. Überprüfen Sie auf vorhandene Probleme, um sicherzustellen, dass Sie keine Anstrengungen duplizieren. Zugewiesene Ausgaben werden als in progress betrachtet. Wenn Sie an einem Problem zusammenarbeiten möchten, wenden Sie sich an die Person, die dem Problem zugewiesen ist.

Ähnlich wie beim PowerShell-RFC-Prozesserstellen Sie ein Problem, bevor Sie den Inhalt schreiben. Die Problematik stellt sicher, dass Sie keine Zeit und Mühe für Arbeit verschwenden, die vom PowerShell-Docs-Team abgelehnt wird. Das Problem bietet uns die Möglichkeit, mit Ihnen den Umfang des Inhalts zu besprechen und festzustellen, wo er in die PowerShell-Dokumentation passt. Alle Artikel müssen in das Inhaltsverzeichnis (Table of Contents, TOC) aufgenommen werden. Der vorgeschlagene Speicherort des Inhaltsverzeichnisses sollte in der Diskussion über die Ausgabe angegeben werden.

Anmerkung

Das Veröffentlichungssystem generiert das Inhaltsverzeichnis automatisch für Referenzinhalte. Sie müssen das Inhaltsverzeichnis nicht aktualisieren.

Aktualisieren vorhandener Artikel

Sofern zutreffend, werden Cmdlet-Referenzartikel in allen Versionen der PowerShell, die in diesem Repository verwaltet werden, dupliziert. Wenn Sie ein Problem mit einer Cmdlet-Referenz oder einem About_-Artikel melden, listen Sie bitte die Versionen des Artikels auf, die das Problem aufweisen.

Wenden Sie die entsprechende Änderung auf jede Version der Datei an.

Lokalisierter Inhalt

Die PowerShell-Dokumentation wird in Englisch geschrieben und in 17 andere Sprachen übersetzt. Der englische Inhalt wird im GitHub-Repository mit dem Namen MicrosoftDocs/PowerShell-Docsgespeichert. Probleme im übersetzten Inhalt sollten an dieses Repository übermittelt werden.

Alle Übersetzungen beginnen mit dem englischen Inhalt. Wir verwenden sowohl menschliche als auch maschinelle Übersetzung.

Übersetzungsmethode	Sprachen
Menschliche Übersetzung	de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, zh-CN, zh-TW
Maschinelle Übersetzung	cs-CZ, hu-HU, nl-NL, pl-PL, pt-PT, sv-SE, tr-TR

Der von der maschinellen Übersetzung übersetzte Inhalt führt möglicherweise nicht immer zu korrekten Wortauswahlen und Grammatiken. Wenn Sie einen Fehler bei der Übersetzung für eine beliebige Sprache finden, anstatt in den technischen Details des Artikels, öffnen Sie ein Problem, das erklärt, warum Sie der Meinung sind, dass die Übersetzung falsch ist.

Einige Übersetzungsprobleme können behoben werden, indem sie die englischen Quelldateien ändern. Einige Probleme können jedoch Updates für unser internes Übersetzungssystem erfordern. In diesen Fällen müssen wir das Problem an unser internes Lokalisierungsteam zur Überprüfung und Antwort übermitteln.

Nächste Schritte

Es gibt zwei gängige Methoden zum Übermitteln von Änderungen in GitHub. Beide Methoden werden im zentralen Leitfaden für Mitwirkende beschrieben:

1. Sie können schnelle Änderungen an bestehenden Dokumenten in der GitHub-Weboberfläche vornehmen.
2. Verwenden Sie den vollständigen GitHub-Workflow zum Hinzufügen neuer Artikel, zum Aktualisieren mehrerer Dateien oder anderer großer Änderungen.

Bevor Sie Änderungen vornehmen, sollten Sie einen Fork des PowerShell-Docs-Repositories erstellen. Die Änderungen sollten in einem Arbeitszweig in Ihrer Kopie der PowerShell-Docs vorgenommen werden. Wenn Sie die Schnellbearbeitungsmethode in GitHub verwenden, werden diese Schritte für Sie durchgeführt. Wenn Sie den vollständigen GitHub Workflow verwenden, müssen Sie festlegen, dass Sie lokal arbeiten.

Beide Methoden enden mit der Erstellung eines Pull Requests (PR). Weitere Informationen und bewährte Methoden finden Sie unter Übermitteln einer Pull-Anforderung.