Ett nytt feedbacksystem kommer till docs.microsoft.com

Den här posten har skrivits av Rob Eisenberg, Senior Program Manager i docs.microsoft.com-teamet.

Microsofts uppgift är att ge människor och organisationer runtom i världen möjlighet att uppnå mer. Det tog vi hänsyn till när vi skapade docs.microsoft.com ovanpå den öppna GitHub-plattformen. Idag tar vi det till nästa nivå i och med flytten till det nya GitHub-baserade systemet för dokumentationsfeedback.

Feedback om innehållet på GitHub

Dokumentationen har ju funnits på GitHub från start, men mekanismen för feedback om innehållet har använt Livefyre för kommentarer om artiklar. Livefyre är en bra lösning för kommentarer, men det visade det sig vara otillräckligt för våra specifika behov att spåra, tilldela ägare och upprätthålla tillståndet för de innehållsproblem kunderna rapporterat.

Vi utforskade ett antal vägar för att göra det bättre, men en fråga som har väglett mycket av vårt arbete verkade dyka upp igen: Om vår dokumentation behandlades precis som öppen källkod, vad skulle vi använda för att lösa detta problem? Svaret på frågan verkade uppenbart: GitHub-problem, så vi började experimentera med att integrera GitHub-API:er djupare i våra dokumentationssidor och kunde skapa ett fullständigt feedbacksystem ovanpå GitHub-infrastrukturen.

Med det nya systemet kan du skapa GitHub-ärenden direkt från en innehållssida, vilket innebär att du kan interagera mycket smidigare med författare och produktgrupper. Ser du något problem med ett dokument? Ett exempel på dålig kod? En förvirrande förklaring? Något viktigt som saknas? Du bläddrar bara längst ned på sidan och väljer att lämna feedback om dokumentationen.

User logging in and leaving feedback

Du kan se alla öppna och stängda ärenden som är kopplade till dokumentet direkt från själva dokumentationssidan. På så sätt är du alltid uppdaterad om när saker och ting åtgärdas och löses:

Showcasing opened and closed issues

Du kan kommentera och även lägga till reaktioner om ärenden som är viktiga för dig:

Adding reactions to GitHub issues

Nu kan Microsofts personal utnyttja hela den potential som GitHub-ärenden erbjuder för att sortera, svara på, planera och åtgärda rapporterade problem – och du har alltid insyn i processen!

Exempel på feedback om dokumentation

Låt oss anta att du rapporterar ett GitHub-ärende om en bruten hyperlänk i en artikel. Vårt team kommer att sortera problemet, tilldela en etikett och en ägare som ska göra korrigeringen (eller ställa uppföljande frågor). När ägaren skickar en pull-begäran som åtgärdar ärendet får du en avisering (utifrån dina inställningar för GitHub-aviseringar) om att ärendet är åtgärdat/stängt, vilket skapar en bra feedbackcykel.

Du kan också utnyttja de vanliga fördelarna med GitHub, till exempel Markdown i kommentarer, prenumerationer på enskilda ärenden eller hela lagringsplatser, RSS-flöden för organisationsaktiviteter, @-omnämnanden, tilldelade personer och mycket annat! Vi tror att en djupare integration med verktyg med öppen kod främjar nya möjligheter med en växande community och ett bättre samarbete.

Uppdelning av feedback om produkten

Ett problem med det tidigare systemet var att feedback om produkter och feedback om dokumentation blandades i en och samma ström. Det innebar att det blev mycket svårt att sortera och följa upp ärenden, eftersom inte alla objekt hade korrekta etiketter. Vi har gjort framsteg i att åtgärda det här problemet genom att skapa ett tydligt sätt att separera dessa två:

Submitting product feedback

När du klickar för att lämna feedback om produkten kommer du nu direkt till den webbplats där produktteamet som är kopplat till just den specifika dokumentationssidan hanterar produktfeedback.

Lansering

Du kanske undrar när feedbacksystemet kommer att vara tillgängligt. Vi har nu testkört det i några månader för Visual Studio IDE och Azure CLI-dokumentationen. I början av februari påbörjar vi lanseringen på hela docs.microsoft.com.

Din feedback

Din feedback är viktig för oss, så vi vill att du ska får tillgång till det nya systemet så fort som möjligt. Det här är vår kommande åtgärd för bättre feedback och mer engagemang på plattformen, med det är verkligen inte den sista åtgärden. Se till att uttrycka dina tankar om ändringarna på GitHub eller tagga oss på Twitter.