Aggiornamento di novembre per docs.microsoft.com

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

Oggi siamo orgogliosi di annunciare che è stata ora eseguita la migrazione della documentazione per Azure, Visual Studio 2017 RC, C++, ASP.NET Core, Entity Framework Core e SQL in Linux per docs.microsoft.com!

Un sito unico per tutta la documentazione offre un'esperienza coerente per utenti, esperti IT, supporto di dispositivi mobili, localizzazione, commenti, condivisione sociale o contributi di community.

Durante e dopo questa migrazione, si continuerà ad aggiornare regolarmente il contenuto e le funzionalità del sito. Per questo motivo, gli utenti sono invitati a inviare commenti e suggerimenti via UserVoice sulla loro esperienza con il contenuto.

Nei prossimi mesi verrà anche aggiunto il contenuto di Dynamics 365, Windows Server, SQL Server, System Center e Windows Desktop.

In questo articolo

• Funzionalità principali di Docs
• Nuove funzionalità di Docs
• Documentazione di Azure
• Documentazione di Visual Studio 2017 RC
• Documentazione di C++
• Documentazione di ASP.NET Core
• Documentazione di base di Entity Framework
• Documentazione di SQL per Linux

Funzionalità principali di Docs

Per coloro che non hanno familiarità con docs.microsoft.com, queste sono alcune delle funzionalità principali di una nuova esperienza.

Tempo di lettura previsto e ultimo aggiornamento

Un semplice miglioramento apportato in base all'input offre un tempo di lettura stimato per un articolo. Sappiamo che molti di voi stanno imparando e valutando le tecnologie durante questi pochi minuti tra riunioni e si è più probabile leggere articoli se si sapeva quanto è necessario un impegno di tempo.

Sono stati aggiunti anche dei time stamp (data e ora) al contenuto per indicare l'ultimo aggiornamento dell'articolo.

Progettazione reattiva

Per creare un'esperienza ottimale su dispositivi mobili, tablet e PC, è stato implementato un layout reattivo. Facendo clic sul pulsante Opzioni nella parte superiore della pagina in dispositivi a schermo ridotto è possibile accedere alle stesse opzioni visualizzate in un browser desktop.

Documentazione globale

Molti utenti ed esperti internazionali hanno molto spesso evidenziato l'importanza del contenuto localizzato. docs.microsoft.com supporta ora 45 lingue, incluse alcune lingue scritte da destra a sinistra, ad esempio arabo ed ebraico, nonché 63 impostazioni locali in totale per il contenuto di Dynamics 365 con logica di fallback in cui i documenti localizzati potrebbero non essere disponibili. In questo modo la documentazione diventa realmente globale ed è pronta per contenuto aggiuntivo durante l'anno prossimo.

Note rapide e commenti

Le domande, i commenti e i suggerimenti sono importanti per Microsoft. Abbiamo collaborato con Livefyre per fornire commenti e note affiancate su tutti i nostri articoli. Nella parte superiore di ogni articolo verrà visualizzata un'opzione per passare direttamente alla sezione commenti.

I commenti e i suggerimenti degli utenti sono benvenuti e il team si impegna a monitorare e rispondere ai quesiti e ai commenti aggiunti nelle pagine di Docs.

Per aggiungere commenti, è possibile accedere con un account Twitter, Facebook, Google, Yahoo esistenti o con credenziali Microsoft.

Sarà inoltre possibile seguire i thread di cui si prevede un seguito. In questo modo si assicura che gli utenti saranno sempre al corrente delle risposte inviate dal team o dai membri delle community.

È anche possibile aggiungere note rapide a ogni paragrafo del contenuto o a testo appositamente evidenziato. A tale scopo, è sufficiente selezionare un blocco di testo con il mouse o fare clic sull'icona del commento visualizzata sul lato destro del paragrafo al passaggio del mouse.

Condivisione nel social networking

Il pulsante di condivisione nella parte superiore della pagina consente di condividere facilmente il contenuto con i follower di Twitter e gli amici di Facebook.

È inoltre possibile selezionare contenuto direttamente con il mouse per condividerlo tramite il widget contestuale.

Tema chiaro / scuro

Abbiamo anche aggiunto un selettore tema in modo che sia possibile cambiare tra una luce e un tema scuro, qualcosa che alcuni di voi hanno [asked for on UserVoice](https://msdocs.uservoice.com/forums/364242-general-site-feedback/suggestions/14999211-komplete-dark-theme).

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

https://technet.microsoft.com/library/dn646983.aspx3

After

https://docs.microsoft.com/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune

Contributi della community

La maggior parte dei documenti sul sito sono abilitati per i contributi delle community. È sufficiente fare clic su pulsante Modifica nel menu in alto a destra per passare alla pagina di GitHub corrispondente, biforcare il repository, apportare una modifica e inviare la richiesta di pull. Il team di Microsoft è lieto di ricevere modifiche sul contenuto localizzato, oltre a commenti e suggerimenti sull'esperienza complessiva.

Nuove funzionalità di Docs

Sebbene molte di queste funzionalità siano disponibili dalla data di lancio di maggio scorso, nel frattempo sono state aggiunte anche altre nuove funzionalità, descritte di seguito.

Filtro in tempo reale del sommario

Il sommario è ora filtrabile in modo istantaneo. Ciò vuol dire che è possibile digitare alcuni caratteri per filtrare il testo corrispondente per trovare il contenuto che si sta cercando.

Sommario nel riquadro di spostamento sinistro

È stata aggiunta un'altra funzionalità fondamentale che risolve il problema del contenuto su più siti. Un articolo sulla distribuzione di un'applicazione ASP.NET nel Servizio app di Azure deve essere elencata sotto Azure o in ASP.NET? In realtà l'articolo verrà elencato in entrambi i siti, senza però duplicare il contenuto in entrambe le sezioni dei siti per motivi di rilevamento e di coerenza.

A tale scopo, è stato consentito ai team responsabili del contenuto di selezionare qualsiasi contenuto in Docs e creare una visualizzazione di tale contenuto per gli utenti. La figura seguente illustra un ipotetico layout per gli sviluppatori .NET tramite Docker che potrebbe avere contenuto pubblicato dai team di ASP.NET, .NET Core e Azure SDK di Visual Studio. Tutto in una singola visualizzazione.

Esempi di codice verificabile

Una delle peculiarità più frustranti della documentazione è quando gli esempi illustrati o collegati non funzionano nel computer in uso. Microsoft offre migliaia di esempi di codice e frammenti di codice ed esegue controlli regolari per assicurare che tali esempi funzionino correttamente sulle piattaforme e configurazioni supportate.

A tale scopo, è stato sviluppato un sistema di integrazione continua (CI) estendibile, per assicurare che gli esempi possano essere compilati correttamente e producano l'output previsto per un determinato set di sistemi operativi e toolchain. Microsoft garantisce che sul codice scaricato dagli utenti sono stati eseguiti i controlli di qualità necessari. Per questa attività di test si stanno reclutando nuovi team.

Contenuto di riferimento integrato

È stato riprogettato il motore DocFX, ovvero il componente open source che alimenta docs.microsoft.com, per includere le associazioni di linguaggi per piattaforme e formati diversi. È incluso il supporto di:

• Interfaccia della riga di comando di Azure (Python)
• PowerShell
• .NET e .NET Core
• Java
• Swagger / API REST

Per gli utenti, ciò significa che la documentazione non dovrà più desincronizzarsi, ovvero perdere la sincronizzazione con le funzionalità API perché ora c'è solo un'origine sicura e coerente per documenti e codice. È possibile leggere altre informazioni sul supporto specifico per API nelle sezioni di Azure e ASP.NET/EF di seguito.

Supporto in formato PDF

Un'altra funzionalità principale richiesta da molti utenti è il supporto in formato PDF. È possibile ora scaricare un set specifico di documenti senza occupare enormi quantità di spazio e leggerlo ovunque e su qualsiasi dispositivo.

A questo scopo, è stato attivato il supporto in formato PDF del sommario. Si garantisce inoltre che il file PDF è aggiornato quando il contenuto sul sito live viene aggiornato, in modo che si possa sempre avere l'ultima versione del contenuto.

<img alt="screenshot16]()

Documentazione di Azure

Abbiamo sentito il feedback sulla frammentazione e sulle sfide con l'esperienza, quindi siamo in grado di eseguire la migrazione della documentazione tecnica di Azure da azure.microsoft.com, MSDN e GitHub e consolidarla in https://docs.microsoft.com/azure/.

Nuova pagina hub di Azure

L'aspetto della pagina di destinazione per il contenuto di Azure è stato cambiato e reso più efficiente. Alcune caratteristiche importanti includono:

• Una scheda Services che elenca i servizi di Azure raggruppati per categoria.
• Una scheda Developer che elenca tutto il contenuto di riferimento di Azure per API REST, .NET SDK di Azure , Java SDK di Azure , interfaccia della riga di comando di Azure e Azure PowerShell.
• Una scheda Architecture destinata ad architetti e sviluppatori per informazioni sui modelli di progettazione con scalabilità cloud.

Nuova pagina del servizio

Le pagine di destinazione sono ora più coerenti e includono collegamenti alle risorse principali, tra cui:

• Collegamento a una panoramica del servizio.
• Esercitazioni introduttive per tutte le piattaforme e i linguaggi di programmazione rilevanti.
• Collegamento a tutte le esercitazioni su video per un determinato servizio.
• Collegamenti al contenuto di riferimento API.
• Collegamento per scaricare tutta la documentazione per un servizio specifico.

Nuovo sommario

Durante la migrazione a docs.microsoft.com/azure si sta migliorando la coerenza nell'esplorazione del sommario. Mentre ogni servizio ha caratteristiche univoche, si noterà che l'esplorazione è simile in tutto il sito.

Colorazione migliorata

Negli esempi di codice che rappresentano l'interfaccia della riga di comando di Azure (CLI), vengono usati colori diversi per parole chiave e parametri in modo che sia più facile leggere e capire il codice.

Miglioramenti nei riferimenti

Uno dei punti più problematici segnalati dagli utenti è che API, riga di comando e contenuto di PowerShell non sono mai aggiornati. Per questo motivo, le modifiche frequenti in Azure impediscono ai flussi di lavoro manuali legacy di funzionare correttamente.

In questa versione sono stati modificati i sistemi per creare riferimenti direttamente dal codice sorgente. Le nuove compilazioni vengono rilasciate insieme a nuovo contenuto. Il modo usato per contribuire al contenuto delle procedure può essere applicato alla parte autogenerata della documentazione.

Si sta anche standardizzando l'uso della Specifica API aperta (precedentemente nota come Swagger) per descrivere l'API REST che offre adesso una rappresentazione coerente dei dati per i servizi REST e può essere usata per documentazione e SDK client. In futuro sarà inoltre possibile aggiungere funzionalità interattive alla documentazione di REST e payload di richiesta/risposta di esempio.

In questa versione sono stati abilitati gli elementi seguenti:

• Interfaccia della riga di comando di Azure 2.0 (anteprima)
• Azure PowerShell
• Azure Java SDK
• Azure .NET SDK
• API REST di Azure

Documentazione di Visual Studio 2017 RC

Si sta introducendo tutta la documentazione di Visual Studio, integrata direttamente nella nuova e aggiornata esperienza di docs.microsoft.com.

Nuova pagina hub di Visual Studio

La pagina hub di Visual Studio include collegamenti chiave per iniziare con la versione finale candidata di Visual Studio 2017.

Questa include la Guida all'installazione, Novità ed esercitazioni introduttive. Sarà presto disponibile il contenuto localizzato. Nuovo contenuto sarà disponibile per alcuni argomenti, ad esempio il refactoring, uso di codice che non si trova in un progetto, problemi di prestazioni di debug, suggerimenti per ottimizzare il tempo di avvio di Visual Studio, informazioni dettagliate su tutte le nuove funzionalità di produttività e di esplorazione del codice nell'editor e altro ancora.

Ora che Visual Studio supporta un processo di installazione completamente personalizzabile, che consente di ottenere solo i componenti che si vuole usare, è possibile conoscerne meglio il funzionamento per i progetti di sviluppo individuali, indipendentemente dal fatto che i carichi di lavoro implicano piattaforme Windows, Azure, Python o ASP.NET.

Documentazione principale di ASP.NET e Entity Framework

La documentazione principale di ASP.NET Core e di Entity Framework è stata anche spostata rispettivamente da docs.asp.net e GitHub.

Guida di riferimento a ASP.NET / Entity Framework

Poiché ASP.NET Core e Entity Framework Core sono progetti open source, sono stati integrati il codice sorgente e i commenti a barra tripla per compilare la rispettiva documentazione di riferimento all'API. Ciò vuol dire che l'API e la documentazione saranno sempre sincronizzate automaticamente.

Documentazione di C++

In risposta alle richieste degli utenti, è stato eseguito il refactoring del manuale di riferimento di C++ in un formato più compatto che richiede un minor numero di collegamenti tra gli argomenti. È possibile ora trovare tutti i documenti per i membri di classe nello stesso argomento della classe.

Inoltre, è possibile acquisire una migliore familiarità con le ultime modifiche di conformità agli standard di C++ e nuove opzioni di compilazione, ad esempio /fastlink, usare il materiale sussidiario di portabilità per aggiornare il codice della versione precedente di Visual Studio e scoprire come provare il nuovo supporto per la compilazione di sistemi Linux con gcc.

Documentazione di SQL per Linux

È ora disponibile una versione di prova di SQL Server per Linux (parte di SQL Server vNext Customer Technical Preview 1). La pagina hub include collegamenti chiave che guidano dalle operazioni fondamentali fino alla gestione e allo sviluppo con SQL Server per Linux. Sarà presto disponibile il contenuto localizzato.

Conclusioni

Verranno preso rese disponibili molte altre funzionalità al nuovo sito della documentazione per assicurare un'esperienza coerente con prodotti e servizi. Poiché l'utente, l'utente, è il pezzo più critico del processo di documentazione, ti invitiamo a contattarci e fornire commenti e suggerimenti su come possiamo migliorare questa esperienza per te su Twitter.