Binnenkort beschikbaar op docs.microsoft.com: een nieuw feedbacksysteem

Deze blogpost is geschreven door Rob Eisenberg, Senior Program Manager van het docs.microsoft.com-team.

Microsoft heeft als missie elke persoon en elke organisatie op de planeet te helpen meer te bereiken. Dit was een van onze overwegingen toen we docs.microsoft.com boven op het open GitHub-platform ontwikkelden. We brengen het nu naar een hoger niveau met de overgang naar een feedbacksysteem voor de documentatie op basis van GitHub.

Feedback op inhoud op GitHub

Onze documentatie staat sinds het begin op GitHub en als mechanisme voor de feedback op inhoud werd gebruikgemaakt van Livefyre voor opmerkingen over artikelen. Hoewel Livefyre een uitstekende oplossing voor reacties is, bleek het niet helemaal aan onze behoeften te voldoen, dat wil zeggen bijhouden, eigenaren toewijzen en de status van door klanten aangegeven problemen met de inhoud beheren.

We hebben een aantal manieren verkend om het te verbeteren, maar één vraag die veel van ons werk heeft geleid, leek opnieuw naar boven te komen: als onze documentatie net zo wordt behandeld als open source code, wat zouden we dan gebruiken om dit probleem op te lossen? Het antwoord op de vraag leek voor de hand te liggen: GitHub-problemen, dus we begonnen te experimenteren met het dieper integreren van GitHub-API's in onze documentatiepagina's, waarbij we een volledig feedbacksysteem konden bouwen op basis van de GitHub-infrastructuur.

Met het nieuwe systeem kunt u nu GitHub-problemen rechtstreeks vanuit een inhoudspagina maken zodat u op een veel uitgebreidere manier kunt communiceren met schrijvers en productteams. Merkt u een probleem met een document op? Een slecht codevoorbeeld? Een verwarrende uitleg? Een belangrijke weglating? Blader gewoon naar de onderkant van de pagina en selecteer Feedback op documentatie geven.

U ziet alle openstaande en gesloten problemen die zijn gekoppeld aan het document, rechtstreeks vanuit de documentatiepagina zelf, zodat u altijd op de hoogte bent als dingen worden gecorrigeerd en opgelost:

U kunt commentaar leveren en zelfs reacties toevoegen aan problemen die voor u belangrijk zijn:

Microsoft-medewerkers kunnen nu gebruikmaken van de volledige kracht van GitHub Issues om gemelde problemen te categoriseren, hierop te reageren, te plannen en op te lossen. U hebt altijd inzicht in het proces!

Voorbeeld van feedback op documentatie

Stel dat u een GitHub-probleem meldt over een verbroken hyperlink in een artikel. Ons team categoriseert het probleem, wijst een label toe en wijst een eigenaar toe die voor de oplossing moet zorgen (of vervolgvragen moet stellen). Wanneer de eigenaar een pull-aanvraag verzendt waarmee het probleem wordt opgelost, krijgt u een bericht (op basis van uw GitHub-meldingsinstellingen) dat het probleem is opgelost/gesloten en wordt er een vicieuze cirkel van feedback tot stand gebracht.

Bovendien kunt u gebruikmaken van alle standaard-GitHub-voorzieningen, zoals Markdown in opmerkingen, registraties voor afzonderlijke problemen of volledige opslagplaatsen, RSS-feeds van organisatieactiviteiten, @-vermeldingen, toegewezen personen en nog veel meer. Wij zijn ervan overtuigd dat een dieper niveau van open source-integratie nieuwe mogelijkheden voor de groei en samenwerking van de community biedt.

Scheiding van productfeedback

Een van de problemen met het vorige systeem is de combinatie van feedback op producten en documentatie in één stroom. Het was heel lastig te categoriseren en op te volgen als niet alle items consistent waren gelabeld. Om dit probleem op te lossen bedachten we een manier om de twee te scheiden:

Door te klikken op Productfeedback geven gaat u nu rechtstreeks naar de site waar het productteam dat aan de specifieke documentatiepagina is gekoppeld, de feedback op het product afhandelt.

Implementatie

U vraagt zich misschien af wanneer het feedbacksysteem beschikbaar zal zijn. We hebben het nu al een aantal maanden uitgeprobeerd voor Visual Studio IDE en de documentatie van Azure CLI. Vanaf half februari beginnen we met de implementatie voor het hele docs.microsoft.com.

Uw feedback

Uw feedback is belangrijk voor ons. Daarom willen we dat u zo gauw mogelijk met het nieuwe systeem kunt werken. Dit is de volgende stap om feedback op en betrokkenheid bij ons platform te verbeteren, maar het is in geen geval de laatste stap. Zorg ervoor dat u uw mening geeft over de wijzigingen op GitHub of tag ons op Twitter.