Ogłoszenie ujednoliconego środowiska dokumentacji programu .NET w witrynie docs.microsoft.com
Autorem tego postu jest Jeff Sandquist, dyrektor naczelny zespołu ds. rozwoju i ekosystemu platformy Azure.
Prawie rok temu pilotowaliśmy dokumentację referencyjną platformy .NET Core dotyczącą docs.microsoft.com. Dzisiaj z przyjemnością ogłaszamy nasze ujednolicone środowisko dokumentacji interfejsu API platformy .NET. Rozumiemy, że produktywność deweloperów jest kluczowa — od dewelopera hobbystycznego po startup po przedsiębiorstwo. Mając to na uwadze, ściśle współpracujemy z zespołem platformy Xamarin, aby ustandaryzować sposób dokumentowania, odnajdywania i nawigowania po interfejsach API platformy .NET w firmie Microsoft.
Cała dokumentacja platformy .NET — w jednym miejscu
Wcześniej, jeśli chcesz znaleźć element . Zestaw SDK oparty na platformie NET dostarczany przez firmę Microsoft musiał poświęcić trochę czasu na ulubioną wyszukiwarkę, próbując znaleźć zarówno miejsce, w którym można go pobrać, jak i zapoznać się z odpowiednią dokumentacją interfejsu API.
W przyszłości planujemy mieć wszystko . Zestawy SDK zgodne z platformą NET są ujednolicone i można wyszukiwać w jednym miejscu: https://docs.microsoft.com/dotnet/api. W tym miejscu znajdziesz dokumentację referencyjną dla .NET Framework, .NET Core, .NET Standard i Xamarin, a także dokumentację naszych pakietów NuGet platformy Azure. W nadchodzących miesiącach dodamy więcej zestawów SDK do tego środowiska.
Wprowadzenie do przeglądarki interfejsu API
Naszym głównym celem jest wprowadzenie środowiska przypominającego funkcję IntelliSense w celu wyszukiwania wszystkich interfejsów API platformy .NET z przeglądarki internetowej. Przestrzeń nazw, klasa, metoda lub interfejs można wyszukać, wpisując pełną lub częściową nazwę bezpośrednio na stronie przeglądarki interfejsu API.
Jeśli nie masz pewności, do którego zestawu SDK należy określony typ, element członkowski lub przestrzeń nazw, możesz po prostu wybrać pozycję Wszystkie interfejsy API na liście rozwijanej Zakres interfejsu API i przeszukać wszystkie dostępne dokumenty referencyjne. Alternatywnie, jeśli chcesz ograniczyć wyszukiwanie, możesz wybrać określoną strukturę lub zestaw SDK, a także jego wersję — na przykład .NET Framework 4.7 i wyszukać tylko w tym zestawie interfejsów API.
Środowisko przeglądarki interfejsu API jest również zintegrowane w górnej części spisu treści dla elementu . Interfejsy API oparte na platformie NET, które umożliwiają szybkie znajdowanie dowolnego interfejsu API niezależnie od tego, gdzie jesteś w dokumentacji referencyjnej:
Gdy znajdujesz się w określonej przestrzeni nazw, przeglądarka interfejsów API jest ograniczona tylko do rodziny połączonych ze sobą interfejsów API, więc wyszukiwanie zawsze zwraca najlepsze możliwe wyniki na podstawie kontekstu.
Obsługa wersji
Nie musisz już zastanawiać się, czy typ ma elementy członkowskie dostępne w określonej wersji .NET Framework, czy pakiet NuGet usługi Azure Storage — wystarczy zmienić wersję kontrolki przeglądarki interfejsu API, a zawartość odpowiednio dostosuje się:
Skompilowany z myślą o rozwiązaniu Open Source
Aby utworzyć przeglądarkę interfejsu API, użyliśmy otwartych standardów i narzędzi. U podstaw korzystaliśmy z narzędzia docFX — otwartego łańcucha narzędzi generowania dokumentacji wraz z aplikacją mdoc platformy Xamarin.
Cała zarządzana dokumentacja referencyjna jest teraz automatycznie generowana na podstawie plików binarnych, które są dostarczane w usłudze NuGet lub są częścią głównych dystrybucji platform, takich jak .NET Framework lub .NET Core.
Nasza infrastruktura ciągłej integracji umożliwia nam posiadanie dokładnej dokumentacji dla najnowszych interfejsów API, które mogą być teraz publiczne w ciągu kilku godzin od wydania, otwarte dla kontrybucyjnych. Ustandaryzowaliśmy również całą dokumentację interfejsu API platformy .NET w formacie ECMAXML, która tworzy spójną i kompleksową reprezentację interfejsu API niezależnie od udokumentowanego zestawu SDK. Ponadto nie musisz znać zawiłości formatu pliku, ponieważ możesz współtworzyć zawartość w języku Markdown osadzoną w automatycznie generowanych dokumentach. Udział społeczności w dokumentacji referencyjnej zostanie włączony w ciągu następnego miesiąca.
Koncentracja na zawartości
Oprócz nowych środowisk zoptymalizowaliśmy również zawartość referencyjną, aby być bardziej czytelna i czytelna. Zaktualizowaliśmy spis treści, aby zawsze był skoncentrowany na przestrzeni nazw. Niezależnie od tego, czy przeglądasz informacje o przestrzeni nazw, typie czy elemencie członkowskim, zawsze wyświetlamy tylko nadrzędną przestrzeń nazw ze wszystkimi typami podrzędnymi & ich grupowanych elementów członkowskich:
Oznacza to, że strony referencyjne są decluttered i pokazują najważniejsze informacje, takie jak ogólne przeglądy i przykłady — wszystko na pierwszy rzut oka.
Zobaczysz również przykłady, które są istotne dla Ciebie bezpośrednio od początku, odfiltrowane do wybranego języka programowania — nie musisz już przewijać do samego dołu strony, aby je znaleźć.
Oparte na opiniach
Jest to dopiero początek modernizacji środowiska dokumentacji referencyjnej. Chcemy poznać Twoją opinię na temat tego, jak możemy sprawić, że nasza dokumentacja będzie bardziej atrakcyjna, przydatna i jak najszybsza. Przejdź do naszej witryny UserVoice i daj nam znać, jak możemy ulepszyć środowisko przeglądarki interfejsu API. Możesz również zawsze skontaktować się z nami na Twitterze, @docsmsft, w celu uzyskania szybkich aktualizacji.