Übersicht über die neue .NET Core-Dokumentation
Dieser Beitrag wurde vom Geschäftsführer der Abteilung „Cloud + Enterprise“, Jeff Sandquist, verfasst.
Heute haben wir eine Vorschau der .NET-Dokumentation auf docs.microsoft.com veröffentlicht. Weitere Informationen zu den neuen Verbesserungen der Dokumentation auf docs.microsoft.com finden Sie im Blogbeitrag zu docs.microsoft.com. Zusätzlich zu all den Kollaborationsfunktionen, Open-Source-Inhalten und benutzerfreundlicheren URLs auf der docs.microsoft.com-Plattform haben wir einige neue Features eingeführt, die speziell für .NET-Entwickler*innen gedacht sind. In diesem Beitrag werden diese neuen Features sowie unsere Pläne für die Zukunft vorgestellt.
Highlights der .NET-Dokumentation
Anlässlich des aktuellen RTM-Releases von .NET Core wird der zugehörige Artikel im Mittelpunkt der Homepage der .NET-Dokumentation angezeigt. Wir haben Links zu Artikeln sowie die neuen Referenzen an die Spitze der Liste gesetzt, um Ihnen alle Ressourcen zur Verfügung zu stellen, die Sie anlässlich des RTM-Releases von .NET Core benötigen.
Das .NET-Ökosystem auf einen Blick
Hier finden Sie Links zum Herunterladen der neuen .NET Core-Bibliotheken, ASP.NET, Entity Framework, Azure, zum Erstellen von iOS-Anwendungen mit Xamarin und zum Erstellen von UWP-Anwendungen (Universelle Windows-Plattform) mit .NET. Wir haben noch nicht alle .NET-Inhalte zu docs.microsoft.com verschoben, aber Sie können von der Homepage der .NET-Dokumentation aus die gesamte .NET-Dokumentation einsehen.
Artikel
Unsere Autor*innen und Techniker*innen sowie einige tatkräftige Communitymitglieder haben unermüdlich daran gearbeitet, neue Artikel zu .NET Core zu schreiben, die Sie im Abschnitt .NET-Dokumentation finden können. Hier finden Sie Artikel wie:
Diese und viele andere Artikel werden im docs.microsoft.com-Design veröffentlicht. Sie finden auf jeder Seite ein übersichtliches Inhaltsverzeichnis, die geschätzte Lesedauer für jeden Artikel und Informationen zu den Autor*innen jedes Artikels.
Alle Artikel zu .NET sind Open-Source und auf GitHub im Dokumentationsrepository des .NET-Teams verfügbar. Wenn Sie Fehler in der Dokumentation finden oder diese verbessern möchten, können Sie dies ganz einfach tun, indem Sie auf die Schaltfläche Bearbeiten im rechten Navigationsbereich der einzelnen Artikel klicken.
Einen Artikel zu bearbeiten ist ganz einfach: Klicken Sie auf die Schaltfläche „Bearbeiten“ in einer der Markdowndateien im Repository, fügen Sie Ihre Inhalte hinzu, und stellen Sie einen Pull Request. Sobald ein Team Ihren Pull Request überprüft und akzeptiert hat, werden Ihre Beiträge innerhalb weniger Minuten auf der Website veröffentlicht.
API-Referenz
Zusätzlich zu den großartigen Inhalten, die von unseren Autor*innen, Techniker*innen und engagierten Communitymitgliedern verfasst werden, haben wir erhebliche Verbesserungen an den Referenzen vorgenommen. Die Referenzen wurden in dieser Vorschauversion vollständig überarbeitet, wobei die gleichen Designprinzipien wie bei den Artikeln auf docs.microsoft.com verwendet wurden.
Wie diese Artikel sind die neuen Referenzseiten dynamisch und wurden nach modernen Webprinzipien entworfen. Auch wurden sie für mobile Geräte optimiert.
Wir haben allen NamespaceseitenType Search (Typensuche) hinzugefügt. Dadurch können Sie ganz einfach nach Typnamen für alle .NET-Typen suchen. Mit jedem Tastendruck wird die Liste der Typen gefiltert, die im linken Navigationsbereich erscheinen. Dieses interessante neue Feature des Referenzbereichs ist in unserem neuen Framework enthalten, das zum Generieren der .NET-Referenzdokumentation verwendet wird. Es ist ein Open-Source-Projekt auf GitHub, das auch als DocFX bekannt ist.
Wenn Sie im linken Navigationsbereich eines beliebigen Namespace auf einzelne Typen klicken, springen Sie direkt zum Einführungsabschnitt der Namespaceseite dieses Typs. Mit einem Klick auf den Namen des Typs im Hauptbereich des Referenzinhalts wird die Detailseite der Klasse angezeigt, die die Vererbungskette der Klasse, die Deklaration und Details zu den Eigenschafts- und Methodenmembern der Klasse enthält.
Für jedes Methodenmember werden Details zu den Parametern und eine Zusammenfassung der Methode angezeigt.
Informations- und Entwicklungsprinzipien
Neben der kontinuierlichen Weiterentwicklung und Verbesserung der DocFX-Tools zur Dokumentenerstellung haben wir die Entwicklungs- und Dokumentationsprinzipien, die in der neuen .NET-Dokumentation zum Einsatz kommen, erheblich verbessert.
Bessere Automatisierung
Wenn wir Pull Requests von potenziellen Mitwirkenden erhalten, überprüfen wir, ob der*die Mitwirkende unsere Lizenzvereinbarung für Mitwirkende unterzeichnet hat (dieser einfache Vorgang erfolgt vollständig elektronisch und nimmt nur wenige Minuten in Anspruch). Wenn die Beiträge den Beitragsrichtlinien entsprechen, sollten kleine Änderungen schon wenige Minuten nach Annahme der Pull Requests auf der Website veröffentlicht werden.
Bessere URLs
Ein wesentlicher Aspekt der gesamten Dokumentation auf docs.microsoft.com sind bessere URLs, mit denen die Suchindizierung und das „Erraten“ verbessert werden. Wir haben diesen Aspekt in der .NET-Dokumentation übernommen. Sowohl die Artikel als auch die Referenzdokumentation verfügen über sauberere URLs. Sehen Sie sich beispielsweise die MSDN-URL für den Systemnamespace an:
In der neuen Referenzdokumentation ist die URL logischer, leichter lesbar und vor allem besser auffindbar.
Agilere und offenere Dokumenterstellung
Die Inhalte sind nicht nur Open Source, und wir akzeptieren nicht nur Communitybeiträge. Darüber hinaus sind alle Inhalte auf docs.microsoft.com (einschließlich der .NET-Dokumentation) unter einer Creative Commons-Lizenz verfügbar. Sie können sie lesen, kopieren, darauf verweisen und Teile davon wiederverwenden (auch für kommerzielle Zwecke). Die Autor*innen und Techniker*innen arbeiten seit Monaten aktiv mit Communitymitgliedern in diesem neuen System zusammen. Dies war eine interessante und spannende Umstellung. Wir haben auch in Zukunft noch vieles vor.
Zukünftige Pläne
Dieser Abschnitt von docs.microsoft.com befindet sich, wie der Rest der Website, noch in der Vorschau. Wir freuen uns daher über konstruktives Feedback und Kommentare. Senden Sie Ihre Ideen zu Features an UserVoice.
In den kommenden Wochen veröffentlichen wir die XML-Kommentare, mit denen die Referenzdokumentation direkt im .NET-Quellcode generiert werden kann. Dadurch kann jede*r auf einfache Weise die Referenzdokumentation zum .NET-Framework aktualisieren.
Wir werden auch weiterhin das Design und das Layout der Referenz sowie die bereits erwähnte Möglichkeit, den Inhalt der Referenz selbst zu bearbeiten, optimieren.
Wir freuen uns, Ihnen den neuen .NET-Dokumentationsbereich auf docs.microsoft.com vorzustellen und möchten die Benutzererfahrung in Zukunft noch weiter verbessern!