Ein neues Feedbacksystem für docs.microsoft.com
Dieser Beitrag wurde von Rob Eisenberg geschrieben, Senior Program Manager des docs.microsoft.com-Teams.
Microsoft verfolgt die Mission, weltweit jeden Menschen und jede Organisation dabei zu unterstützen, höhere Ziele zu erreichen. Dies haben wir u.a. berücksichtigt, als wir docs.microsoft.com zusätzlich zur offenen GitHub-Plattform erstellt haben. Heute gehen wir mit dem Umstieg auf ein neues GitHub-basiertes Dokumentationsfeedbacksystem einen Schritt weiter.
Feedback zu Inhalten auf GitHub
Unsere Dokumentation ist zwar bereits auf GitHub verfügbar, seit dieser Dienst existiert, aber unser Mechanismus für Feedback zu Inhalten hat bislang Livefyre für Kommentare zu Artikeln verwendet. Livefyre eignet sich zwar gut für Kommentare, erfüllt unsere Anforderungen im Hinblick auf die Nachverfolgung, das Zuweisen von Benutzern und die Verwaltung des Status der von Kunden erstellten Issues zu Inhalten jedoch nicht.
Wir haben eine Reihe von Möglichkeiten untersucht, um dies zu verbessern, aber eine Frage, die einen Großteil unserer Arbeit bestimmte, tauchte immer wieder auf: Wenn unsere Dokumentation wie Open-Source-Code behandelt werden würde, was würden wir verwenden, um dieses Problem zu lösen? Die Antwort auf die Frage schien offensichtlich: GitHub Issues. Daher haben wir damit begonnen, GitHub-APIs besser in unsere Dokumentationsseiten zu integrieren, um ein vollständiges Feedbacksystem auf der Grundlage der GitHub-Infrastruktur zu erstellen.
Sie können jetzt mit dem neuen System GitHub-Issues direkt über eine Inhaltsseite erstellen, wodurch Sie viel besser mit den Verfassern und Produktteams interagieren können. Haben Sie ein Problem in einem Dokument gefunden? Ein ungültiges Codebeispiel? Eine verwirrende Erläuterung? Wurde ein wichtiger Punkt ausgelassen? Scrollen Sie einfach ans Ende der Seite, und klicken Sie auf Feedback zum Inhalt.
Auf der Dokumentationsseite werden alle offenen und geschlossenen Issues zu diesem Dokument angezeigt. Dadurch können Sie stets prüfen, ob ein Problem bereits gelöst wurde:
Sie können Issues, die für Sie von Bedeutung sind, kommentieren und sogar darauf reagieren.
Microsoft-Mitarbeiter können jetzt GitHub-Issues im vollen Umfang nutzen, um gemeldete Probleme zu selektieren, auf diese zu reagieren und sie zu beheben – und dabei haben Sie stets Einblick in den Prozess.
Beispielfeedback zu einer Dokumentation
Angenommen, Sie öffnen ein GitHub-Issue aufgrund eines fehlerhaften Links zu einem Artikel. Anschließend selektiert unser Team das Problem und weist ihm eine Bezeichnung und einen Besitzer zu, der es beheben oder Rückfragen stellen soll. Wenn der Besitzer einen Pull Request übermittelt, durch den das Problem behoben wird, werden Sie (abhängig von Ihren Benachrichtigungseinstellungen für GitHub) benachrichtigt, dass das Problem gelöst bzw. geschlossen wurde. Dadurch entsteht ein positiver Feedbackkreislauf.
Außerdem können Sie sämtliche Vorteile von GitHub nutzen, z.B. Markdown in Kommentaren, Abonnements für einzelne Issues oder vollständige Repositorys und RSS-Feeds zu Aktivitäten einer Organisation. Zudem können Sie Personen mithilfe eines @-Zeichens erwähnen und jemandem die Issues zuweisen. Wir glauben, dass durch die Ausweitung der Integration von Open Source-Tools neue Möglichkeiten geschaffen werden, um die Community zu vergrößern und besser mit ihr zusammenzuarbeiten.
Separates Feedback zu Produkten
Bei dem vorherigen System bestand das Problem, dass Produkt- und Dokumentationsfeedback nicht klar voneinander getrennt wurden. Dadurch war es schwierig, zu selektieren und erforderliche Maßnahmen zu ermitteln, wenn die Probleme nicht gewissenhaft mit den passenden Bezeichnungen versehen wurden. Wir haben einen Weg gefunden, die beiden Feedbackbereiche voneinander zu trennen, und hoffen, damit dieses Problem lösen zu können:
Wenn Sie auf Feedback zu Produkten klicken, werden Sie jetzt direkt auf die Website weitergeleitet, über die das Produktteam, das für die betreffende Dokumentationsseite zuständig ist, Produktfeedback bearbeitet.
Rollout
Jetzt möchten Sie sicher wissen, ab wann Sie das Feedbacksystem verwenden können. Ein Pilotversuch läuft bereits seit zwei Monaten für die Visual Studio-IDE und die Azure CLI-Dokumentation. Ab Mitte Februar werden wir dies nach und nach für die gesamte docs.microsoft.com-Website einführen.
Senden Sie Feedback
Ihr Feedback ist für uns von großer Bedeutung, und wir möchten Ihnen das neue System schnellstmöglich zur Verfügung stellen. Unsere Arbeit ist aber mit der Verbesserung des Feedbacks und der Beteiligung an unserer Plattform noch lange nicht beendet. Teilen Sie uns Ihre Meinung zu den Änderungen auf GitHub mit, oder taggen Sie uns auf Twitter.