Wprowadzenie dokumentacji platformy .NET Core

Ten wpis został napisany przez Jeffa Sandquista, dyrektora naczelnego działu Cloud + Enterprise.

Dzisiaj opublikowaliśmy wersję zapoznawcza dokumentacji platformy .NET w docs.microsoft.com. Aby dowiedzieć się więcej na temat nowych ulepszeń środowiska dokumentacji docs.microsoft.com ofert, odwiedź wpis w blogu wprowadzenie docs.microsoft.com. Oprócz wszystkich funkcji współpracy, zawartości typu open source i bardziej przyjaznych adresów URL dostępnych na platformie docs.microsoft.com wprowadziliśmy kilka nowych funkcji specyficznych dla deweloperów platformy .NET. Ten wpis wyróżni te nowe funkcje i podsumuje nasze plany na przyszłość.

Najważniejsze informacje o środowisku dokumentacji platformy .NET

Aby towarzyszyć ekscytującej wersji RTM platformy .NET Core, umieszczamy ją na pierwszej stronie głównej dokumentacji platformy .NET. Aby uzupełnić wersję .NET Core RTM wszystkim, co trzeba szybko rozpocząć, umieściliśmy linki do artykułów i nowego środowiska referencyjnego w górnej części listy.

Ekosystem platformy .NET na wyciągnięcie ręki

Zobaczysz linki do pobierania nowych bibliotek platformy .NET Core, ASP.NET, Platformy Entity Framework, platformy Azure przy użyciu platformy Xamarin do kompilowania aplikacji systemu iOS przy użyciu platformy .NET i tworzenia aplikacji platforma uniwersalna systemu Windows (UWP) przy użyciu platformy .NET. Nie przenieśliśmy jeszcze całej zawartości platformy .NET do docs.microsoft.com, ale strona główna dokumentacji platformy .NET będzie punktem początkowym, aby uzyskać dostęp do całej dokumentacji platformy .NET.

Artykuły

Nasi autorzy i inżynierowie, a także kilku dedykowanych członków społeczności, pracowali niestrudzenie nad tworzeniem nowych artykułów związanych z platformą .NET Core, które znajdziesz w sekcji Dokumentacja platformy .NET . Tutaj znajdziesz szereg artykułów, takich jak:

• Samouczki platformy .NET Core
• Wdrażanie aplikacji platformy .NET Core
• Testowanie jednostkowe na platformie .NET Core

Te i wiele innych tematów są prezentowane w temacie docs.microsoft.com, z czystym spisem treści na każdej stronie, a także szacowanym czasem czytania każdego artykułu i informacji współautora dla każdego artykułu.

Wszystkie artykuły platformy .NET są typu open source i dostępne w witrynie GitHub w repozytorium dokumentacji zespołu platformy .NET. Jeśli znajdziesz jakiekolwiek problemy w dokumentacji lub chcesz je poprawić, wystarczy kliknąć przycisk edycji w prawym obszarze nawigacji każdego artykułu.

Edytowanie artykułu jest tak proste, jak kliknięcie przycisku edycji w dowolnym z plików markdown w repozytorium, dodanie zawartości i przesłanie żądania ściągnięcia. Gdy jeden z naszych zespołów dokona recenzji i zaakceptuje Twoje żądanie ściągnięcia, twoje wkłady będą na żywo w witrynie w ciągu kilku minut.

Dokumentacja interfejsu API

Oprócz świetnej zawartości tworzonej przez naszych pisarzy, inżynierów i namiętnych członków społeczności wprowadziliśmy znaczące ulepszenia środowiska referencyjnego. Środowisko referencyjne zostało całkowicie przeprojektowane w tej wersji zapoznawczej, korzystając z tych samych zasad projektowania używanych w artykułach docs.microsoft.com.

Podobnie jak w przypadku tych artykułów, nowe strony referencyjne są dynamiczne, zaprojektowane z nowoczesnymi zasadami internetowymi i będą wyglądać lepiej na urządzeniach przenośnych.

Dodaliśmy wyszukiwanie typów do wszystkich stron przestrzeni nazw. Dzięki temu można łatwo wyszukiwać według nazwy typu dla wszystkich typów platformy .NET. Po każdym naciśnięciu klawiszy filtrujemy listę typów wyświetlanych w obszarze nawigacji po lewej stronie. Ta ekscytująca nowa funkcja obszaru referencyjnego jest zawarta w naszej nowej strukturze do generowania dokumentacji referencyjnej platformy .NET znanej jako DocFX, projektu open source w usłudze GitHub.

Po kliknięciu poszczególnych typów w obszarze nawigacji po lewej stronie dla dowolnej przestrzeni nazw przeskokniesz bezpośrednio do sekcji wprowadzenia do tego typu strony przestrzeni nazw. Klikając nazwę typu w głównym obszarze zawartości referencyjnej, zobaczysz stronę szczegółów klasy, która zawiera łańcuch dziedziczenia, deklarację i szczegóły dotyczące właściwości i składowych metody klasy.

Dla każdego elementu członkowskiego metody zostaną wyświetlone szczegółowe informacje na temat parametrów i podsumowanie metody.

Zasady dotyczące informacji i inżynierii

Oprócz ciągłego opracowywania i ulepszania narzędzi do generowania dokumentów DocFX wprowadziliśmy znaczące ulepszenia zasad inżynierii i dokumentacji, które będą widoczne w nowym środowisku dokumentacji platformy .NET.

Lepsza automatyzacja

Po otrzymaniu żądań ściągnięcia od potencjalnych współautorów zweryfikujemy, że współautor wykona prosty proces podpisania umowy licencyjnej współautora (ten proces jest w pełni elektroniczny i trwa kilka minut). O ile wkład jest zgodny z wytycznymi dotyczącymi współtworzenia, małe zmiany powinny pojawić się na żywo w witrynie kilka minut po zaakceptowaniu żądań ściągnięcia.

Lepsze adresy URL

Jedną z ważnych zasad ogólnego środowiska docs.microsoft.com jest lepsze adresy URL, aby poprawić indeksowanie wyszukiwania i "odgadywanie". Ta zasada została zachowana w dokumentacji platformy .NET. Zarówno artykuły, jak i dokumentacja referencyjna mają czystsze adresy URL. Weźmy na przykład klasyczny adres URL MSDN dla przestrzeni nazw systemu:

W nowej dokumentacji referencyjnej adres URL jest bardziej logiczny, czytelny dla człowieka i co najważniejsze, bardziej czytelny.

Więcej agile i open authoring

Zawartość nie tylko jest typu open source, a nie tylko akceptujemy wkład społeczności. Ponadto cała zawartość docs.microsoft.com (w tym dokumentacja platformy .NET) jest dostępna w ramach licencji Creative Commons. Można go odczytać, skopiować, odwołać się do niego i ponownie użyć ich części (nawet do użytku komercyjnego). Autorzy i inżynierowie aktywnie pracują z członkami społeczności od miesięcy w nowym systemie. To było interesujące i ekscytujące przejście, a my mamy więcej, aby przyjść w przyszłości.

Przyszłe plany

Ta sekcja docs.microsoft.com, podobnie jak reszta witryny, jest nadal w wersji zapoznawczej, więc zachęcamy do konstruktywnych opinii i komentarzy. Prześlij swoje pomysły dotyczące funkcji do usługi UserVoice.

W najbliższych tygodniach opublikujemy komentarze XML używane do generowania dokumentacji referencyjnej bezpośrednio w kodzie źródłowym platformy .NET. Umożliwi to każdemu łatwe kliknięcie aktualizacji dokumentacji referencyjnej .NET Framework.
Będziemy również nadal dostosowywać projekt i układ odwołania, a także wyżej wymienioną możliwość edytowania samej zawartości referencyjnej.

Cieszymy się, że udostępnimy ci nowy obszar dokumentacji platformy .NET w docs.microsoft.com i czekamy na lepsze środowisko w przyszłości!