Nuovo sistema di invio dei commenti per docs.microsoft.com

Questo post è stato creato da Rob Eisenberg, Senior Program Manager del team docs.microsoft.com.

L'obiettivo principale di Microsoft è quello di offrire a ogni utente e organizzazione i mezzi necessari a ottenere risultati sempre migliori. Questo obiettivo è stato al centro della creazione di docs.microsoft.com sulla base della piattaforma aperta GitHub. Da oggi è disponibile un nuovo sistema di feedback per la documentazione basato su GitHub.

Feedback sui contenuti in GitHub

La documentazione è sempre stata basata su GitHub, mentre per i commenti relativi agli articoli è stato usato Livefyre. Pur essendo un'ottima soluzione per i commenti, Livefyre si è rivelato insufficiente per esigenze contingenti, ad esempio per tenere traccia delle segnalazioni sul contenuto, assegnare proprietari ai problemi corrispondenti e aggiornare lo stato del problema.

Abbiamo esplorato un certo numero di strade per renderlo migliore, ma una domanda che ha guidato gran parte del nostro lavoro sembrava risorgere: se la documentazione fosse trattata proprio come open source codice, cosa useremo per risolvere questo problema? La risposta alla domanda sembrava ovvia: Problemi di GitHub, quindi abbiamo iniziato a sperimentare l'integrazione delle API GitHub più approfondite nelle pagine della documentazione, essendo in grado di creare un sistema di feedback completo all'interno dell'infrastruttura GitHub.

Con il nuovo sistema è ora possibile creare segnalazioni di problemi in GitHub direttamente da una pagina di contenuto, con un'interazione molto più completa con gli autori e i team di prodotto. Si supponga di trovare in un documento uno dei seguenti problemi. Un esempio di codice non pertinente. Una spiegazione poco chiara. Oppure un'omissione importante. È sufficiente scorrere n basso nella pagina e selezionare Give documentation feedback (Feedback sulla documentazione).

È possibile visualizzare direttamente nella pagina della documentazione tutte le segnalazioni aperte e chiuse associate al documento, in modo da essere al corrente dell'implementazione delle soluzioni:

È possibile inserire commenti e aggiungere repliche alle segnalazioni di problemi ritenute importanti:

Ora i dipendenti Microsoft possono sfruttare al meglio Problemi di GitHub per filtrare, pianificare, risolvere i problemi e rispondere alle segnalazioni, mentre l'utente dispone di visibilità completa sul processo.

Esempio di commenti per la documentazione

Ad esempio l'utente aggiunge una segnalazione di GitHub relativa a un collegamento interrotto in un articolo. Il team Microsoft valuta il problema, aggiunge un'etichetta e assegna un responsabile per la soluzione del problema (oppure formula domande aggiuntive). Quando il proprietario invia una richiesta pull che corregge il problema, l'utente riceve una notifica della chiusura/soluzione (in base alle impostazioni di notifica di GitHub) che completa il ciclo di feedback.

Sono anche disponibili tutte le utili funzionalità di GitHub, ad esempio Markdown nei commenti, sottoscrizioni a singole segnalazioni o interi archivi, feed RSS sulle attività dell'organizzazione, citazioni con @, assegnatari e così via. Microsoft ritiene che un livello più completo di integrazione con gli strumenti open source possa promuovere nuove opportunità di crescita e collaborazione nella community.

Separazione del feedback sul prodotto

Uno dei problemi del sistema precedente era la combinazione tra feedback sul prodotto e sulla documentazione in un unico flusso. Ciò complicava la valutazione e il completamento, specie quando non tutti gli elementi erano contrassegnati in modo coerente. Un passo importante per la risoluzione di questo problema è stata la definizione di una separazione chiara tra le due entità:

Quando si fa clic su Give product feedback (Feedback sul prodotto) si passa direttamente al sito in cui il team del prodotto associato alla pagina di documentazione gestisce i commenti e i suggerimenti sul prodotto.

Implementazione

Le tempistiche di attivazione del sistema di commenti sono indicate di seguito. Il sistema è stato testato negli ultimi due mesi per Visual Studio IDE e per la documentazione dell'interfaccia della riga di comando di Azure. A partire da metà febbraio il nuovo sistema verrà implementato nell'intero sito docs.microsoft.com.

Commenti e suggerimenti

Il feedback degli utenti è importante, pertanto Microsoft desidera implementare il nuovo sistema quanto prima. Questa nuova soluzione è solo una fase nel lavoro destinato a migliorare il sistema di commenti e il coinvolgimento degli utenti nella piattaforma. Assicurarsi di inserire i tuoi pensieri sulle modifiche in GitHub o tagarci su Twitter.