November-Update für docs.microsoft.com
Dieser Beitrag wurde vom Geschäftsführer der Abteilung „Cloud + Enterprise“, Jeff Sandquist, verfasst.
Wir sind stolz, heute bekanntgeben zu können, dass wir die Dokumentation für Azure, Visual Studio 2017 RC, C++, ASP.NET Core, Entity Framework Core und SQL unter Linux nun zu docs.microsoft.com migriert haben.
Das Zusammenführen unseres gesamten Inhalts führt für unsere Kunden zu einer konsistenteren Benutzererfahrung bei der mobilen Unterstützung, der Lokalisierung, bei Kommentaren, beim Teilen in sozialen Netzwerken und beim Beitragen in der Community.
Obwohl es sich dabei um ein umfangreiches Release handelt, werden wir die Inhalts- und Websitefunktionen weiterhin regelmäßig aktualisieren. Senden Sie uns daher bitte UserVoice-Feedback zur Benutzerfreundlichkeit des Inhalts.
Sie können Sich zudem auf Inhalt über Dynamics 365, Windows Server, SQL Server, System Center und Windows-Desktop freuen, der in den nächsten Monaten hinzugefügt wird.
- Hauptmerkmale der Dokumentation
- Neue Funktionen der Dokumentation
- Dokumentation zu Azure
- Visual Studio 2017 RC-Dokumentation
- C++-Dokumentation
- ASP.NET Core-Dokumentation
- Entity Framework Core-Dokumentation
- SQL unter Linux-Dokumentation
Für diejenigen unter Ihnen, die nicht mit docs.microsoft.com vertraut sind, haben wir hier einige der wichtigsten Funktionen der neuen Benutzeroberfläche aufgelistet.
Eine einfache Verbesserung, die wir basierend auf Ihren Rückmeldungen vorgenommenen haben, ist die Angabe einer geschätzten Lesezeit für einen Artikel. Wir wissen, dass viele von Ihnen in den wenigen Minuten zwischen Besprechungen über Technologien lernen und sie bewerten, sodass Sie Artikel eher lesen werden, wenn Sie den erforderlichen Zeitaufwand dafür kennen.
Wir haben Inhalten zudem Zeitstempel hinzugefügt, damit Kunden sehen können, wie aktuell der Inhalt ist. Sie müssen nun nicht mehr raten, wann ein Artikel zum letzten Mal aktualisiert wurde.
Zum Erstellen einer überzeugenden Benutzeroberfläche auf mobilen Geräten, Tablets und PCs haben wir ein responsives Layout implementiert. Indem Sie auf Geräten mit kleinem Bildschirm auf die Schaltfläche Optionen oben auf der Seite klicken, können Sie auf die gleichen Optionen zugreifen, die Ihnen auf einem Desktopbrowser angezeigt werden.
Internationale Kunden haben immer wieder die Bedeutung von lokalisiertem Inhalt betont. docs.microsoft.com unterstützt nun 45 Sprachen, einschließlich Sprachen, die von rechts nach links geschrieben werden, wie z.B. Arabisch und Hebräisch, sowie insgesamt 63 Gebietsschemas für Dynamics 365-Inhalte mit Fallbacklogik, für die lokalisierte Dokumentationen möglicherweise nicht zur Verfügung stehen. Dadurch kann unsere Dokumentation wirklich von Kunden aus aller Welt genutzt werden und ist bereit für den zusätzlichen Inhalt, der im neuen Jahr hinzugefügt wird.
Ihre Fragen, Kommentare und Rückmeldungen sind uns sehr wichtig. Wir haben uns mit Livefyre zusammengetan, damit Kommentare und Randnotizen zu allen unseren Artikeln bereitgestellt werden können. Am Anfang jedes Artikels finden Sie eine Option, um direkt zum Kommentarabschnitt zu wechseln.
Wir möchten von Ihnen hören und werden alle Kommentare und Fragen beobachten und beantworten, die auf den Dokumentationsseiten hinterlassen werden.
Um einen Kommentar zu hinterlassen, können Sie sich mit Ihren vorhandenen Twitter-, Facebook-, Google-, Yahoo- oder Microsoft-Anmeldeinformationen anmelden.
Darüber hinaus können Sie den Threads folgen, für die Sie Antworten erwarten. Erfahren Sie immer sofort, wenn eines unserer Team- oder Communitymitglieder Ihnen geantwortet hat.
Sie können auch Randbemerkungen zu jedem Absatz des Inhalts oder speziell hervorgehobenem Text hinzufügen. Wählen Sie hierzu einfach mit dem Mauszeiger einen Textblock aus, oder klicken Sie auf das Kommentarsymbol, das am rechten Rand des Abschnitts erscheint, wenn Sie darauf zeigen.
Über die Schaltfläche „Teilen“ oben auf der Seite können Sie unseren Inhalt einfach mit Ihren Twitter- und Facebook-Freunden teilen.
Sie können Inhalt auch direkt mit der Maus auswählen, um diesen über das Kontextwidget zu teilen.
Wir haben auch eine Designauswahl hinzugefügt, damit Sie zwischen einem hellen und einem dunklen Design wechseln können, etwas, das einige von Ihnen haben [asked for on UserVoice](https://msdocs.uservoice.com/forums/364242-general-site-feedback/suggestions/14999211-komplete-dark-theme)
.
Die Erfahrung auf unserer Website ist uns wichtig, weshalb uns als Benutzer von TechNet oder MSDN eine Sache regelmäßig gestört hat, nämlich dass Artikel keine benutzerfreundlichen, lesbaren URLs hatten. Hier ist ein Beispiel desselben Artikels mit unseren neuen URLs.
https://technet.microsoft.com/library/dn646983.aspx3
https://docs.microsoft.com/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune
Die Community kann zu einem Großteil der Dokumentation Beiträge leisten. Klicken Sie einfach auf die Schaltfläche Bearbeiten im Menü oben rechts, um zur entsprechenden GitHub-Seite zu wechseln, verzweigen Sie das Repository, nehmen Sie eine Änderung vor, und senden Sie Ihre Pull-Anforderung. Wir freuen uns über Bearbeitungen von lokalisiertem Inhalt und auch über allgemeines Feedback zur Funktion, mit der Sie beitragen können.
Während viele dieser Funktionen schon seit unserem Starttag im Mai verfügbar sind, haben wir zudem einige neue Funktionen hinzugefügt, die nachstehend beschrieben sind.
Unser Inhaltsverzeichnis kann nun sofort gefiltert werden. Dies bedeutet, dass Sie einfach nur ein paar Zeichen eingeben müssen, um nach etwaigem übereinstimmenden Text zu filtern, um den Inhalt zu finden, nach dem Sie suchen.
Eine weitere wichtige Funktion, die wir hinzugefügt haben, bezieht sich auf das Problem von Inhalt auf mehreren Websites. Sollte ein Artikel zum Bereitstellen einer ASP.NET-App in Azure App Service unter Azure oder unter ASP.NET aufgelistet werden? Die Antwortet lautet „sowohl als auch“. Aus Gründen der Erkennbarkeit und der Konsistenz sollte der Inhalt jedoch nicht auf beiden Websiteabschnitten dupliziert werden.
Deshalb können Inhaltsteams jeden Inhalt der Dokumentationen auswählen und eine Ansicht dieses Inhalts für Kunden erstellen. Die nachstehende Abbildung zeigt ein hypothetisches Layout für .NET-Entwickler, die Docker verwenden und möglicherweise über Inhalt verfügen, der von den Teams für Azure, ASP.NET, .NET Core und Visual Studio Azure SDK stammt, wobei alles in einer einzigen Ansicht angezeigt wird.
Einer der frustrierendsten Punkte der Dokumentation ist, wenn die dargestellten oder verknüpften Beispiele auf Ihrem Computer tatsächlich nicht funktionieren. Bei Microsoft verfügen wir über Tausende von Codebeispielen und Codeausschnitten, und wir möchten sicherstellen, dass unsere Kunden sich darauf verlassen können, dass diese Beispiele auf den unterstützten Plattformen und Konfigurationen funktionieren.
Zu diesem Zweck haben wir ein erweiterbares CI-System (Continuous Integration) entwickelt, um sicherzustellen, dass die Beispiele kompilieren und dass die Ausgabe für eine angegebene Reihe von Betriebssystemen und Toolketten den Erwartungen entspricht. Während wir daran arbeiten, weitere Teams in dieses System zu integrieren, möchten wir sicherstellen, dass Benutzer, die unseren Code herunterladen, darauf vertrauen können, dass dieser alle erforderlichen Qualitätsprüfungen bestanden hat.
Wir haben die zugrunde liegende Engine DocFX (die Open Source-Komponente, die docs.microsoft.com betreibt) überarbeitet, um Sprachbindungen für verschiedene Plattformen und Formate einzuschließen. Unter anderem werden folgende Elemente unterstützt:
- Azure-Befehlszeilenschnittstelle (Python)
- PowerShell
- .NET und .NET Core
- Java
- Swagger/REST-APIs
Für Kunden bedeutet dies, dass die Dokumentation nicht mehr von den API-Funktionen abweicht, da nun eine einheitliche Datenbasis vorhanden ist, die sowohl die Dokumentation als auch den Code steuert. In den nachstehenden Abschnitten zu Azure und ASP.NET/EF können Sie mehr über die spezifische Unterstützung für die API-Referenz lesen.
Eine weitere wichtige Funktion, nach der Kunden gefragt haben, ist die PDF-Unterstützung. Sie können eine bestimmte Reihe von Dokumentationen herunterladen, ohne dass diese mehrere Gigabyte an Speicherplatz benötigen, und sie überall hin mitnehmen, unabhängig davon, ob Sie ein Desktopgerät oder ein mobiles Gerät verwenden.
Um dies zu ermöglichen, haben wir die PDF-Unterstützung für unser Inhaltsverzeichnis aktiviert. Wir haben sichergestellt, dass die PDF-Datei aktualisiert wird, wenn der Inhalt auf der Live-Website aktualisiert wird, damit Sie immer den neuesten und besten Inhalt erhalten.
<img alt="screenshot16]()
Wir haben Ihr Feedback zur Fragmentierung und zu den Herausforderungen der Benutzeroberfläche zur Kenntnis genommen und befinden uns auf einem guten Weg, unsere technische Azure-Dokumentation von azure.microsoft.com, MSDN und GitHub zu migrieren und auf https://docs.microsoft.com/azure/ zusammenzuführen.
Wir haben auch die Möglichkeit genutzt, das Erscheinungsbild der Angebotsseite für Azure-Inhalt zu ändern. Einige wichtige Highlights umfassen Folgendes:
- Eine Registerkarte Dienste, die Azure-Dienste nach Kategorie getrennt auflistet.
- Eine Registerkarte Entwickler, die den gesamten Azure-Referenzinhalt für die REST-API, das Azure .NET SDK, das Azure Java SDK, die Azure-Befehlszeilenschnittstelle und Azure PowerShell auflistet.
- Eine Registerkarte Architektur für Architekten und Entwickler, um mehr über Cloudentwurfsmuster zu erfahren.
Wir haben sichergestellt, dass unsere Landing Page konsistent sind und auf wichtige Ressourcen verlinken, einschließlich:
- Einem Link zur Dienstübersicht.
- Erste Schritte-Tutorials für alle relevanten Plattformen und Programmiersprachen.
- Einem Link zu allen Videotutorials für einen bestimmten Dienst.
- Links zum API-Referenzinhalt.
- Einem Link, um die gesamte Dokumentation für diesen Dienst herunterzuladen.
Während wir zu docs.microsoft.com/azure wechseln, nutzen wir die Gelegenheit, die Konsistenz unserer Inhaltsverzeichnisnavigation zu verbessern. Obwohl jeder Dienst über einzigartige Eigenschaften verfügt, ist die Navigation nun überall ähnlich, wenn Sie sich auf der Website bewegen.
Für Codebeispiele, die die Azure-Befehlszeilenschnittstelle (Azure-CLI) darstellen, haben wir die Farbgebung für Schlüsselwörter und Parameter hinzugefügt, damit es für Sie einfacher ist, unseren Code zu lesen und zu verstehen.
Einer der größten Problempunkte, auf die Sie uns aufmerksam gemacht haben, ist, dass unsere API-, Befehlszeilen- und PowerShell-Inhalte nie auf dem neuesten Stand sind. Unsere älteren manuellen Workflows funktionieren nicht so schnell wie Azure-Änderungen.
Für dieses Release haben wir unsere Systeme dahingehend geändert, dass sie Verweise direkt aus Quellcode erstellen. Wenn neue Builds übermittelt werden, wird auch neuer Inhalt übermittelt. So wie Sie Beiträge für unseren Inhalt zu Vorgehensweisen erstellen können, können Sie dies auch für den automatisch generierten Teil der Dokumentation tun.
Wir standardisieren auch die Verwendung der Open API-Spezifikation (früher als Swagger bekannt), um unsere REST-APIs zu beschreiben, wodurch wir nun eine konsistente Datendarstellung für REST-Dienste erhalten, die für die Dokumentation verwendet werden kann, sowie Client SDKs. In Zukunft werden wir zu unserer REST-Dokumentation und unseren Beispiel-Anforderung/Antwort-Nutzlasten auch interaktive Funktionen hinzufügen können.
Für dieses Release haben wir Folgendes aktiviert:
- Azure-Befehlszeilenschnittstelle 2.0 (Preview)
- Azure PowerShell
- Azure Java SDK
- Azure .NET SDK
- Azure-REST-APIs
Wir führen die gesamte Visual Studio-Dokumentation ein, die direkt in die neue und aktualisierte Benutzeroberfläche von docs.microsoft.com integriert wird.
Die Visual Studio-Hubseite enthält wichtige Links zu den ersten Schritten mit dem Release Candidate von Visual Studio 2017.
Dies umfasst das Installationshandbuch, Neuigkeiten und Erste Schritte-Tutorials. Lokalisierter Inhalt wird in Kürze verfügbar sein. Neuer Inhalt wird u.a. für folgende Themen zur Verfügung stehen: Refactoring, Arbeiten mit Code, der nicht in einem Projekt vorhanden ist, Debuggen von Leistungsproblemen, Tipps für die Optimierung der Visual Studio-Startzeit, Details zu allen neuen Produktivitäts- und Codenavigationsfunktionen im Editor usw.
Visual Studio unterstützt nun einen vollständig anpassbaren Installationsvorgang, bei dem Sie nur die Komponenten erhalten, die Sie verwenden möchten. Sie können mehr darüber erfahren, wie dies bei Ihren individuellen Entwicklungsprojekten funktioniert, unabhängig davon, ob Ihre Arbeitsauslastungen ASP.NET-, Azure-, Python- oder Windows-Plattformen beinhalten.
Die ASP.NET Core- sowie Entity Framework Core-Dokumentation wurden ebenfalls von „docs.asp.net“ bzw. GitHub migriert.
Da es sich bei ASP.NET Core und Entity Framework Core um Open Source-Projekte handelt, haben wir deren Quellcode und Kommentare mit dreifachem Schrägstrich direkt integriert, um die entsprechende API-Referenzdokumentation zu erstellen. Dies bedeutet, dass die API und die Dokumentation dauerhaft automatisch synchronisiert werden.
Als Reaktion auf langjährige Anfragen von Kunden haben wir die C++-Referenz in ein kompakteres Format umgestaltet, das weniger Links zwischen Themen erfordert. Nun finden Sie alle Dokumente für Klassenmember im gleichen Thema wie die Klasse.
Erfahren Sie darüber hinaus mehr über die neuesten C++-Standardkonformitätsänderungen und neue Buildoptionen wie /fastlink
, verwenden Sie die neue Anleitung zum Portieren, um Ihren Code aus früheren Versionen von Visual Studio upzugraden, und erfahren Sie, wie Sie die neue Unterstützung für die Erstellung auf Linux-Systemen mit gcc
testen.
SQL Server unter Linux (Teil von SQL Server vNext Customer Technical Preview 1) steht nun zur Verfügung und kann von Ihnen getestet werden. Die Hubseite enthält wichtige Links, die Sie von den ersten Schritten bis zum Verwalten und Entwickeln mit SQL Server unter Linux leitet. Lokalisierter Inhalt wird in Kürze verfügbar sein.
Wir bemühen uns, noch mehr Funktionen für die neue Dokumentationswebsite bereitzustellen und sicherzustellen, dass die Benutzeroberfläche mit unseren Produkten und Diensten konsistent ist. Da Sie, der Benutzer, der wichtigste Teil des Dokumentationsprozesses sind, empfehlen wir Ihnen, sich an uns zu wenden und Feedback zu geben, wie wir diese Erfahrung für Sie auf Twitter verbessern können.