Presentazione di docs.microsoft.com

Questo articolo è stato scritto da Jeff Sandquist, General Manager di Cloud + Enterprise Division.

Oggi viene annunciata la versione di anteprima del nuovo servizio di documentazione, con contenuti che supportano i prodotti Enterprise https://docs.microsoft.com Mobility.

Perché docs.microsoft.com?

Perché il contenuto è importante. Abbiamo svolto interviste e sondaggi con centinaia di sviluppatori e professionisti IT e analizzato i commenti degli utenti sul sito Web nel corso degli anni con UserVoice. Abbiamo capito che era necessario apportare una modifica e creare un'esperienza Web moderna riguardo al contenuto. Il primo passo è stato valutare l'infrastruttura di contenuto esistente, TechNet e MSDN. Entrambi i siti sono compilati su una codebase fragile di 10-15 anni con un sistema di pubblicazione e distribuzione antiquato che non è stato progettato per l'esecuzione nel cloud.

Dovevamo concentrarci non solo sull'esperienza, ma anche sul contenuto creato e sul modo in cui viene usato da ogni utente. Per anni i clienti ci hanno chiesto di andare oltre i lunghissimi post con contenuto a livello di funzionalità e di aiutarli a implementare soluzioni per i problemi aziendali. Sapevamo che il contenuto messo a disposizione e la piattaforma che abbiamo creato devono semplificare le procedure di apprendimento e distribuzione delle soluzioni per i clienti.

Abbiamo capito che per ottenere un'esperienza complessiva ottimale era necessario iniziare da zero: da questo impegno è nato https://docs.microsoft.com, un nuovo approccio alla documentazione Microsoft.

Nota: questa versione di anteprima del sito Web include il contenuto *only* per la documentazione sulla mobilità di Enterprise (costituita da Advanced Threat Analytics,Azure Active Directory,App remota di Azure,Multi-Factor Authentication,Azure Rights Management,Intunee Microsoft Identity Manager). In futuro, man mano che la nostra piattaforma matura con l'aiuto di commenti e suggerimenti degli utenti, trasferiremo altra documentazione in questa esperienza.

Funzionalità principali

Si inizierà con una pagina della documentazione di esempio illustrata di seguito e verranno presentate alcune delle nuove funzionalità nel sito.

Documentation Example

Leggibilità

Per migliorare la leggibilità, il sito è stato modificato in modo che il contenuto abbia una larghezza limitata. Gli studi di tracciamento oculare hanno dimostrato che è possibile migliorare la comprensione e la velocità di lettura con una larghezza del contenuto impostata perché è difficile per l'occhio seguire lunghi passaggi da sinistra a destra. Per spiegare meglio questo concetto, di seguito è riportato un esempio di articolo di Intune pubblicato in docs.microsoft.com seguito dallo stesso articolo pubblicato in TechNet. Sono state anche aumentate le dimensioni del carattere per lo spostamento a sinistra e il testo stesso, cosa che i clienti hanno chiesto (UserVoice - Aumenta dimensione carattere).

Docs and TechNet comparison

Tempo di lettura stimato

Un altro semplice miglioramento apportato in base all'input è fornire un tempo di lettura stimato per un articolo. Molti di voi stanno imparando/valutando la tecnologia pochi minuti tra una riunione e l'altra ed è più probabile leggere articoli se si è a conoscenza della quantità di tempo necessaria per l'impegno. Abbiamo anche aggiunto ai contenuti indicatori di data che consentono ai clienti di capire quanto sono aggiornate le informazioni in base al feedback in UserVoice.

Estimated reading time

Contenuto e navigazione nel sito

Un'area chiave di investimento basata sulle colloqui con i clienti e sui commenti e suggerimenti di UserVoice è stata il miglioramento della navigazione nel sito, dell'architettura delle informazioni e dell'organizzazione dei contenuti in base alle finalità del cliente. Abbiamo suddiviso il contenuto in raggruppamenti logici relativi a valutazione, attività iniziali, pianificazione, distribuzione, gestione o risoluzione dei problemi di prodotti o servizi. È possibile visualizzare il contenuto così suddiviso nel menu di navigazione a sinistra e nelle pagine di prodotti o servizi.

Di seguito è riportata la schermata della pagina iniziale della documentazione di Intune:

Intune documentation screenshot

La stessa categorizzazione è usata anche nel menu di navigazione degli articoli a sinistra:

Left navigation

Riduzione della lunghezza degli articoli

Un altro feedback comune è che il contenuto a volte può essere eccessivo a causa della sua lunghezza e che gli articoli lunghi sono più difficili da esplorare e trovare ciò che si sta cercando. Per risolvere questo problema, sono stati suddivisi molti articoli più lunghi in passaggi logici più piccoli e sono stati forniti i pulsanti Indietro e Avanti nella parte inferiore degli articoli per spostarsi tra i passaggi di un'esercitazione in più parti, come illustrato di seguito.

Back and Next buttons

Se è vero che molti clienti apprezzano le esercitazioni suddivise in più parti, altri hanno detto di preferire la possibilità di combinare i vari passaggi di un'esercitazione in un unico PDF stampabile offline. Non abbiamo ancora questa opzione, ma sarà presto disponibile per l'anteprima.

Progettazione reattiva

Per creare un'esperienza ottimale su dispositivi mobili, tablet e PC in base alle richieste degli utenti in UserVoice, siamo passati a un layout reattivo. Facendo clic sul pulsante Opzioni, la schermata viene espansa o compressa in modo da visualizzare le stesse opzioni così come appaiono sul desktop.

Responsive Page Design

Contributi della community

Tutta la documentazione su docs.microsoft.com è open source e progettata per consentire i contributi della community. Questo approccio segue quello di altri team di Microsoft che hanno già reso open source, completamente o in parte, la loro documentazione, ad esempio ASP.NET, Azure, .NET Core e Microsoft Graph.

Ogni articolo contiene un pulsante di modifica (come nell'illustrazione che segue) che consente di accedere al file markdown di origine in GitHub, dove è possibile inviare facilmente una richiesta pull per correggere o migliorare il contenuto.

Meccanismi di feedback

Le domande, i commenti e i suggerimenti sono importanti per Microsoft. Abbiamo collaborato con Livefyre per fornire commenti e note laterali su tutti gli articoli. Nella parte superiore di ogni articolo verrà visualizzato un collegamento per i commenti, come illustrato di seguito.

Comments link

Facendo clic sui commenti si passa alla parte inferiore della pagina in cui è possibile eseguire l'accesso (con le credenziali di Twitter, Facebook, Google, Yahoo o Microsoft) per aggiungere o seguire commenti o indicare "Mi piace".

Comments at bottom

È anche possibile aggiungere note a margine a ogni paragrafo del contenuto o in particolare al testo evidenziato. A tale scopo, con il cursore del mouse sul simbolo del commento a destra, fare clic per aggiungere un commento inline.

Sidenote example

Condivisione nel social networking

Il pulsante di condivisione nella parte superiore della pagina consente di condividere facilmente le informazioni con Twitter e Facebook.

Sharing to Twitter and Facebook

È anche possibile usare il cursore del mouse per selezionare il contenuto in un articolo e aggiungere un commento o condividere le informazioni su Facebook o Twitter direttamente dal menu di scelta rapida, come illustrato di seguito.

Select and comment or share content

URL descrittivi

L'esperienza sul Web è importante e una cosa che sicuramente disturba gli utenti di TechNet e MSDN è il fatto che gli articoli non hanno URL descrittivi e leggibili. Ecco un esempio dello stesso articolo con i nuovi URL.

  • Prima:

  • Dopo:

Temi del sito Web

Abbiamo aggiunto un selettore del tema agli articoli in modo che sia possibile passare da un tema scuro a uno chiaro e viceversa, un richiesta fatta da alcuni utenti in UserVoice.

Light and Dark Theme Selector

La figura che segue illustra la differenza tra il tema chiaro e il tema scuro.

Light and Dark themes

Fundamentals

Aspetti importanti come le prestazioni del sito sono elementi chiave che molti clienti hanno chiesto di migliorare in UserVoice. La velocità di caricamento delle pagine in docs.microsoft.com è superiore del 50-300% e la distribuzione geografica è sensibilmente migliorata rispetto al passato. È stata anche creata un'architettura che esegue il 100% in Azure.

Microsoft vuole conoscere l'opinione degli utenti.

Ci auguriamo che la versione preliminare di docs.microsoft.com sia di vostro gradimento e vi invitiamo a inviare commenti e suggerimenti all'indirizzo https://aka.ms/sitefeedback. Nei post futuri verranno illustrati i piani per migliorare notevolmente l'esperienza per il contenuto di riferimento e i piani per la localizzazione dei contenuti.