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

Willkommen beim Leitfaden für Mitwirkende an unserer Dokumentation auf docs.microsoft.com.

Einige der Dokumentationssammlungen von Microsoft sind Open-Source und werden auf GitHub gehostet. Nicht alle Dokumentationssammlungen sind vollständig frei verfügbar. Für viele gibt es aber öffentliche Repositorys, in denen Sie über Pull Requests vorgeschlagene Änderungen vornehmen 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 zu benötigten Dokumentationen.
  • Durch die öffentliche Prüfung in Open-Source-Repositorys können wir mit dem ersten Release den bestmöglichen Inhalt veröffentlichen.
  • Durch öffentliche Updates in Open-Source-Repositorys können wir Inhalt kontinuierlich verbessern.

Die Benutzeroberfläche auf docs.microsoft.com bezieht GitHub-Workflows direkt ein, 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 Tickets 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 alternativ 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. Neue oder signifikante Änderungen haben einen Kommentar im Pull Request zur Folge, in dem Sie gebeten werden, online eine Lizenzvereinbarung für Beiträge (Contribution License Agreement, CLA) zu akzeptieren. Dies gilt, wenn Sie kein Mitarbeiter von Microsoft sind. Sie müssen das Onlineformular ausfüllen, damit wir Ihren Pull Request prüfen oder annehmen können.

Schnelle Änderungen an vorhandenen Dokumenten

Schnelle Änderungen optimieren das Melden und Beheben von geringfügigen Fehlern und Auslassungen in Dokumenten. Trotz aller Bemühungen kommt es zu geringfügigen Grammatik- und Rechtschreibfehlern in unseren Dokumenten. Sie können Tickets erstellen, um Fehler zu melden – es ist jedoch schneller und einfacher, einen Pull Request (PR) 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 auf Bearbeiten klicken, werden Sie zur Quelldatei auf GitHub weitergeleitet. Wenn die Schaltfläche Bearbeiten fehlt, bedeutet dies, dass die Dokumentationsseite nicht für Änderungen verfügbar ist.

    Ort des Links „Bearbeiten“

    Wenn die Schaltfläche Bearbeiten nicht angezeigt wird, bedeutet dies, dass der Inhalt nicht für öffentliche Beiträge freigegeben ist.

  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.

    Ort des Bleistiftsymbols

  3. Nehmen Sie im Web-Editor die Änderungen vor. Klicken Sie auf die Registerkarte Preview changes (Vorschau der Änderungen), um sich das Format Ihrer Änderungen anzusehen.

  4. Wenn Sie alle gewünschten Änderungen vorgenommen haben, scrollen Sie auf der Seite ganz nach unten. Geben Sie einen Titel und eine Beschreibung für Ihre Änderungen ein, und klicken Sie wie unten dargestellt auf Propose file change (Dateiänderung vorschlagen):

    Propose file change

  5. Jetzt haben Sie Ihre Änderungen vorgeschlagen und müssen die Besitzer des Repositorys bitten, Ihre Änderungen in ihr Repository zu „pullen“. Dies erfolgt mit einem sogenannten „Pull Request“. Wenn Sie Propose file change (Dateiänderung vorschlagen) auswählen, wird eine neue Seite ähnlich der folgenden angezeigt:

    Pull Request erstellen

    Wählen Sie Create pull request aus (Pull Request erstellen), geben Sie einen Titel (und optional eine Beschreibung) für den Pull Request ein, und klicken Sie auf Create pull request. Wenn Sie neu bei GitHub sind, finden Sie unter About Pull Requests (Über Pull Requests) wichtige Informationen zum Einstieg.

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

Die GitHub-Benutzeroberfläche zum Bearbeiten spiegelt Ihre Berechtigungen für das Repository wider. Die oben aufgeführten Abbildungen gelten für Mitwirkende, die keine Schreibberechtigungen für das Zielrepository haben. GitHub erstellt automatisch einen Fork des Zielrepositorys in Ihrem Konto. Wenn Sie Schreibberechtigungen für das Zielrepository haben, erstellt GitHub einen neuen Branch im Zielrepository. Der Branchname folgt dem Format <GitHubId>-patch-n mit Ihrer GitHub-ID und einem numerischen Bezeichner für den Patchbranch.

Wir verwenden Pull Requests für alle Änderungen, auch für Mitwirkende mit Schreibberechtigungen. In den meisten Repositorys ist der Standardbranch geschützt, damit Änderungen als Pull Requests gesendet 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

Für die 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. Lediglich die Azure-Dokumentation stellt eine Ausnahme dar. Für azure-docs gibt es öffentliche und lokalisierte GitHub-Repositorys, in denen Communitybeiträge für sechs Sprachen zulässig sind: Chinesisch, Französisch, Deutsch, Japanisch, Koreanisch und Spanisch. Für alle anderen Sprachen und Inhalte müssen Sie die E-Mail-Vorlage verwenden, die für alle Sprachen vorgesehen ist, um Übersetzungsfehler oder technisches Feedback anzumerken.

Prüfen offener PRs

Sie können neue Artikel vor der Veröffentlichung lesen, indem Sie sich die aktuell 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 Pull Requests 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 der Dokumentationsseiten von Microsoft weisen unten auf der Seite einen Abschnitt Feedback auf, in dem Sie auf Produktfeedback oder Inhaltsfeedback klicken 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 erhalten Sie Informationen zum produktiven Mitwirken an der Microsoft-Dokumentation. Dort erfahren Sie, wie Sie mit GitHub-Repositorys, Markdown-Tools und Erweiterungen der Plattform für Microsoft-Dokumentationen arbeiten können.