Leitfaden für Mitwirkende an der Microsoft-Dokumentation: Übersicht

Willkommen beim Leitfaden für Mitwirkende an der Microsoft-Dokumentation auf docs.microsoft.com.

Einige der Dokumentationssammlungen von Microsoft sind Open-Source und werden auf GitHub gehostet. Nicht alle Dokumentsammlungen sind vollständig frei verfügbar. Für viele gibt es aber öffentliche Repositorys, in denen Sie über Pull Requests Änderungen vorschlagen können. Dieser Open-Source-Ansatz optimiert und verbessert die Kommunikation zwischen Produkttechnikern, Inhaltsteams und Kunden. Außerdem bietet er weitere Vorteile:

  • Durch die öffentliche Planung in Open-Source-Repositorys erhalten wir Feedback, welche Dokumente am dringendsten benötigt werden.
  • Durch die öffentliche Prüfung in Open-Source-Repositorys können wir die hilfreichsten Inhalte mit dem ersten Release veröffentlichen.
  • Durch öffentliche Updates in Open-Source-Repositorys können wir Inhalte kontinuierlich verbessern.

In der Benutzeroberfläche der Microsoft-Dokumentation sind GitHub-Workflows direkt integriert, um den Prozess noch einfacher zu gestalten. Beginnen Sie mit dem Bearbeiten des angezeigten Dokuments. Alternativ können Sie neue Artikel prüfen oder nützliche Issues erstellen.

Wichtig

Für alle Repositorys, die Veröffentlichungen auf docs.microsoft.com durchführen, gilt der Verhaltenskodex von Microsoft Open-Source oder von .NET Foundation (beide in englischer Sprache). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Wenden Sie sich mit Ihren Fragen oder Kommentaren an opencode@microsoft.com oder conduct@dotnetfoundation.org.

Für kleinere Korrekturen oder Klarstellungen zu Dokumentation und Codebeispielen in öffentlichen Repositorys gelten die Nutzungsbestimmungen zu docs.microsoft.com. Bei neuen oder signifikanten Änderungen wird im Pull Request ein Kommentar generiert, in dem Sie gebeten werden, online eine Lizenzvereinbarung für Beiträge (Contribution License Agreement, CLA) zu übermitteln, wenn Sie nicht bei Microsoft angestellt sind. Sie müssen das Onlineformular ausfüllen, bevor wir Ihren Pull Request prüfen oder annehmen können.

Schnelle Bearbeitungen der Dokumentation

Schnelle Bearbeitungen optimieren das Melden und Beheben von kleinen Fehlern und Auslassungen in der Dokumentation. Trotz aller Bemühungen kommt es zu geringfügigen Grammatik- und Rechtschreibfehlern in unseren Dokumenten. Sie können Issues erstellen, um Fehler zu melden – es ist jedoch schneller und einfacher, einen Pull Request zum Beheben des Fehlers zu erstellen, wenn diese Option verfügbar ist.

  1. Einige Seiten der Dokumentation ermöglichen Ihnen, Inhalte direkt im Browser zu bearbeiten. Wenn dies der Fall ist, wird eine Schaltfläche Bearbeiten angezeigt, wie unten gezeigt. Wenn Sie Bearbeiten auswählen, werden Sie zur Quelldatei auf GitHub weitergeleitet.

    Location of the edit article link.

    Wenn die Schaltfläche Bearbeiten nicht angezeigt wird, bedeutet dies, dass der Inhalt nicht für öffentliche Beiträge freigegeben ist. Einige Seiten werden generiert (z. B. aus der Inlinedokumentation im Code) und müssen in dem Projekt bearbeitet werden, zu dem sie gehören.

  2. Wählen Sie das Stiftsymbol aus, um den Artikel zu bearbeiten. Wenn das Stiftsymbol abgeblendet ist, müssen Sie sich mit Ihrem GitHub-Konto anmelden oder ein neues Konto erstellen.

    Location of the fork and edit pencil icon.

  3. Bearbeiten Sie die Datei im Web-Editor. Wählen Sie die Registerkarte Vorschau aus, um die Formatierung Ihrer Änderungen zu überprüfen.

  4. Wenn Sie die Bearbeitung abgeschlossen haben, scrollen Sie zum Ende der Seite. Geben Sie im Bereich Änderungen vorschlagen einen Titel und optional eine Beschreibung für Ihre Änderungen ein. Der Titel ist die erste Zeile der Commitnachricht. Wählen Sie Änderungen vorschlagen aus, um Ihre Änderungen zu übernehmen:

    Propose and commit file changes.

  5. Nachdem Sie Änderungen vorgeschlagen und committet haben, müssen Sie jetzt die Besitzer des Repositorys bitten, einen Pull Ihrer Änderungen in ihr Repository auszuführen. Dies erfolgt mit einem sogenannten „Pull Request“ (PR). Wenn Sie Änderungen vorschlagen auswählen, wird eine neue Seite ähnlich der folgenden angezeigt:

    Compare changes and create pull request.

    Klicken Sie auf Pull Request erstellen. Geben Sie den Titel und eine Beschreibung für den Pull Request ein, und wählen Sie dann Pull Request erstellen aus. Wenn Sie neu bei GitHub sind, finden Sie unter Info zu Pull Requests wichtige Informationen zum Einstieg.

  6. Das ist alles! Das Inhaltsteam sieht sich Ihren PR an und mergt ihn nach der Genehmigung. Möglicherweise können Gebühren anfallen.

Die GitHub-Benutzeroberfläche zum Bearbeiten spiegelt Ihre Berechtigungen für das Repository wider. Die Abbildungen oben gelten für Mitwirkende, die keine Schreibberechtigungen für das Zielrepository haben. GitHub erstellt automatisch einen Fork des Zielrepositorys in Ihrem Konto. Der neu erstellte Forkname weist standardmäßig das Format GitHubUsername/RepositoryName auf. Wenn Sie Schreibberechtigungen für das Zielrepository (z. B. Ihren Fork) haben, erstellt GitHub einen neuen Branch im Zielrepository. Der Branchname weist das Standardformat patch-n mit einem numerischen Bezeichner für den Patchbranch auf.

Wir verwenden PRs für alle Änderungen, auch für Mitwirkende mit Schreibzugriff. In den meisten Repositorys ist der Standardbranch geschützt, daher müssen Updates als PRs eingereicht werden.

Das Bearbeiten im Browser eignet sich am besten für geringfügige oder seltene Änderungen. Wenn Sie umfangreichere Änderungen vornehmen oder erweiterte Git-Features verwenden (z.B die Branchverwaltung oder erweiterte Auflösung von Mergekonflikten), müssen Sie einen Fork für das Repository erstellen und lokal arbeiten.

Hinweis

Bei den meisten lokalisierten Dokumentationen ist es nicht möglich, diese über GitHub zu bearbeiten oder Feedback über GitHub abzugeben. Verwenden Sie die unter aka.ms/DocSiteLocFeedback verfügbare E-Mail-Vorlage, um Feedback zu lokalisierten Inhalten abzugeben.

Prüfen offener PRs

Sie können neue Themen vor der Veröffentlichung lesen, indem Sie sich die Warteschlange mit offenen PRs ansehen. Diese Prüfung folgt dem GitHub-Flow. Sie können sich vorgeschlagene Änderungen oder neue Artikel in öffentlichen Repositorys ansehen. Prüfen Sie diese, und fügen Sie eigene Kommentare hinzu. Sie können beliebige Dokumentationsrepositorys aufrufen und sich offene PRs für Themenbereiche ansehen, die Sie interessieren. Vom Feedback der Community zu vorgeschlagenen Änderungen profitiert die gesamte Community.

Erstellen nützlicher Tickets

Unsere Dokumentationen können fortlaufend geändert und verbessert werden. Mit nützlichen Tickets können wir uns immer auf das konzentrieren, was für die Community am wichtigsten ist. Je ausführlicher die Informationen im Ticket, desto nützlicher ist dieses für uns. Sagen Sie uns, welche Informationen Sie gesucht haben. Nennen Sie uns die Suchbegriffe, die Sie verwendet haben. Wenn Ihnen der Einstieg schwerfällt, dann sagen Sie uns einfach, wie Sie sich am liebsten mit neuen Technologien vertraut machen würden.

Viele Seiten der Microsoft-Dokumentation enthalten unten einen Abschnitt Feedback, in dem Sie Produktfeedback oder Inhaltsfeedback eingeben können, um Probleme nachzuverfolgen, die spezifisch für diesen Artikel sind.

Durch Tickets erfahren wir, wo Verbesserungsbedarf besteht. Das Inhaltsteam reagiert dann auf diese Tickets mit Veränderungsvorschlägen und holt Ihre Meinung dazu ein. Nachdem wir einen Entwurf veröffentlicht haben, können Sie den PR prüfen.

Beteiligen Sie sich

In anderen Artikeln in diesem Leitfaden erhalten Sie Informationen zum produktiven Mitwirken an der Microsoft-Dokumentation. Dort erfahren Sie, wie Sie mit GitHub-Repositorys, Markdowntools und Erweiterungen der Microsoft-Dokumentationsplattform arbeiten.