Listopadowa aktualizacja witryny docs.microsoft.com

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

Dzisiaj z dumą ogłaszamy, że przeprowadziliśmy migrację dokumentacji dla platformy Azure, programu Visual Studio 2017 RC, C++, ASP.NET Core, platformy Entity Framework Core i języka SQL w systemie Linux do docs.microsoft.com!

To połączenie zawartości zapewni spójność środowiska dla naszych klientów na potrzeby obsługi technologii mobilnych, lokalizacji, komentarzy, udostępniania w społeczności oraz materiałów przekazywanych przez społeczność.

Choć jest to duże przedsięwzięcie, będziemy regularnie aktualizować zawartość i funkcje witryny, dlatego pamiętaj o wysłaniu opinii w usłudze UserVoice na temat zawartości.

Możesz także spodziewać się nowej zawartości dotyczącej usługi Dynamics 365, systemu Windows Server, programu SQL Server, programu System Center i systemu Windows dla komputerów stacjonarnych.

W tym wpisie

• Najważniejsze funkcje witryny Docs
• Nowe funkcje witryny Docs
• Dokumentacja platformy Azure
• Dokumentacja programu Visual Studio 2017 RC
• Dokumentacja języka C++
• Dokumentacja platformy ASP.NET Core
• Dokumentacja platformy Entity Framework Core
• Dokumentacja programu SQL w systemie Linux

Najważniejsze funkcje witryny Docs

Jeśli jeszcze nie znasz witryny docs.microsoft.com, oto kilka z jej najważniejszych funkcji.

Szacowany czas czytania i Ostatnia aktualizacja

Proste ulepszenie, które wprowadziliśmy na podstawie danych wejściowych, to szacowany czas czytania artykułu. Wiemy, że wielu z Was uczy się i ocenia technologie w ciągu tych kilku minut między spotkaniami i częściej czytasz artykuły, jeśli wiesz, ile czasu jest wymagane.

Dodaliśmy również sygnatury czasowe do zawartości, aby ułatwić klientom sprawdzenie aktualności zawartości. Nie trzeba już zgadywać ostatniej daty aktualizacji artykułu.

Elastyczne środowisko

Aby zapewnić doskonałe środowisko dla urządzeń przenośnych, tabletów i komputerów, wprowadziliśmy układ dynamiczny. Klikając przycisk Opcje w górnej części strony na urządzeniu z małym ekranem, uzyskasz dostęp do tych samych opcji co w przypadku przeglądarki na komputerze stacjonarnym.

Dokumentacja globalna

Klienci międzynarodowi wielokrotnie podkreślali znaczenie zlokalizowanej zawartości. Witryna docs.microsoft.com obsługuje teraz 45 języków, w tym również te zapisywane od prawej do lewej, takie jak arabski czy hebrajski, oraz łącznie 63 ustawienia lokalne dla zawartości dotyczącej usługi Dynamics 365 z logiką rezerwową, gdy zlokalizowane dokumenty są niedostępne. Dzięki temu witryna Docs jest prawdziwie globalna i gotowa na dodatkową zawartość, która pojawi się w nowym roku.

Notatki boczne i komentarze

Pytania, komentarze i opinie użytkowników są dla nas bardzo ważne. Nawiązaliśmy współpracę z Livefyre w celu udostępnienia komentarzy i notatek bocznych we wszystkich naszych artykułach. W górnej części każdego artykułu zobaczysz opcję bezpośredniego przechodzenia do sekcji komentarzy.

Chcemy poznać opinie użytkowników, dlatego angażujemy się w monitorowanie wszystkich komentarzy i pytań napisanych na stronach witryny Docs oraz reagowanie na nie.

Aby dodać komentarz, możesz zalogować się przy użyciu poświadczeń istniejącego konta w usłudze Twitter, Facebook, Google lub Yahoo bądź konta Microsoft.

Ponadto będzie możliwe śledzenie wątków, w których spodziewasz się pojawienia dodatkowych informacji. Dzięki temu nigdy nie przegapisz odpowiedzi członka naszego zespołu lub członka społeczności.

Do każdego akapitu zawartości lub specjalnie wyróżnionego tekstu możesz również dodawać notatki boczne. W tym celu po prostu wybierz fragment tekstu za pomocą kursora myszy lub kliknij ikonę komentarza wyświetlaną po prawej stronie akapitu po umieszczeniu nad nim kursora.

Udostępnianie w społeczności

Przycisk udostępniania w górnej części strony pozwala łatwo udostępniać zawartość osobom obserwującym Cię w usłudze Twitter lub znajomym w usłudze Facebook.

Zawartość możesz także zaznaczyć bezpośrednio za pomocą myszy i udostępnić ją za pośrednictwem kontekstowego widgetu.

Jasny/ciemny motyw

Dodaliśmy również selektor motywu, aby można było zmienić między jasnym i ciemnym motywem, czyli coś, co niektórzy z Was mają [asked for on UserVoice](https://msdocs.uservoice.com/forums/364242-general-site-feedback/suggestions/14999211-komplete-dark-theme).

Przyjazne dla użytkownika adresy URL

Środowisko sieci Web jest dla nas bardzo ważne. Jako użytkowników witryn TechNet i MSDN zawsze irytowało nas to, że artykuły nie mają przyjaznych, łatwych do odczytania adresów URL. Oto przykład tego samego artykułu z nowymi adresami URL.

Stary adres

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

Po

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

Współtworzenie w ramach społeczności

Większość dokumentów w naszej witrynie może być współtworzona przez społeczność. Wystarczy kliknąć przycisk Edytuj w menu znajdującym się w prawym górnym narożniku, aby przejść do odpowiedniej strony usługi GitHub, rozwidlić repozytorium, wprowadzić zmianę i przesłać żądanie ściągnięcia. Zachęcamy także do edytowania zlokalizowanej zawartości i przekazywania opinii na temat środowiska współtworzenia!

Nowe funkcje witryny Docs

Duża część z tych funkcji była dostępna już od dnia uruchomienia witryny w maju, jednak dodaliśmy wiele nowych funkcji, które opisano poniżej.

Filtrowanie spisu treści w czasie rzeczywistym

Włączyliśmy funkcję natychmiastowego filtrowania spisu treści. Oznacza to, że wystarczy wpisać kilka znaków, aby przefiltrować pasujący tekst i znaleźć odpowiednią zawartość.

Spis treści w lewym panelu nawigacyjnym

Kolejna ważna funkcja, którą dodaliśmy, jest odpowiedzią na problem z zawartością znajdującą się na wielu witrynach. Czy artykuł na temat wdrażania aplikacji ASP.NET do usługi Azure App Service powinien znajdować się w obszarze platformy Azure, czy ASP.NET? Odpowiedź brzmi: tu i tu, ale (z przyczyn dotyczących odnajdywania i spójności) bez duplikowania zawartości w obu sekcjach witryny.

W tym celu umożliwiamy zespołom ds. zawartości wybieranie dowolnej zawartości w witrynie Docs i tworzenie widoku tej zawartości dla klientów. Na poniższym obrazie przedstawiono, jak mógłby wyglądać hipotetyczny układ dla deweloperów .NET korzystających z platformy Docker, którzy mogą posiadać zawartość dostarczaną z zespołów Azure, ASP.NET, .NET Core i Visual Studio Azure SDK — wszystko w jednym widoku.

Weryfikowalne przykłady kodu

W przypadku dokumentacji najbardziej irytujące sytuacje mają miejsce wtedy, gdy przykłady, które przedstawiono lub do których podano linki, w rzeczywistości nie działają na danej maszynie. Posiadamy tysiące przykładów i fragmentów kodu i chcemy, aby nasi klienci mieli pewność, że te przykłady będą działać na obsługiwanych platformach i konfiguracjach.

W tym celu opracowaliśmy rozszerzalny system ciągłej integracji, który zapewnia, że przykłady się kompilują i dają oczekiwane wartości wyjściowe dla danego zestawu systemów operacyjnych i łańcuchów narzędzi. Pracujemy nad zaangażowaniem w to większej liczby zespołów i jednocześnie chcemy zapewnić użytkowników pobierających nasz kod, że przejdzie on wszystkie niezbędne kontrole jakości.

Zintegrowane materiały referencyjne

Przeprojektowaliśmy podstawowy aparat DocFX (składnik typu open source obsługujący witrynę docs.microsoft.com) tak, aby obsługiwał powiązania językowe dla różnych platform i formatów. Obejmuje to obsługę następujących elementów:

• Azure CLI (Python)
• PowerShell
• .NET i .NET Core
• Java
• Swagger / Interfejsy API REST

Oznacza to, że dokumentacja nie powinna już dryfować poza synchronizacją z możliwościami interfejsu API, ponieważ obecnie istnieje jedno źródło prawdy, które napędza zarówno dokumentację, jak i kod. Więcej informacji na temat obsługi dokumentacji interfejsu API znajdziesz w poniższych sekcjach dotyczących platform Azure i ASP.NET/EF.

Obsługa plików PDF

Kolejną ważną funkcją, o którą prosili klienci, jest obsługa plików PDF. Umożliwia ona pobranie określonego zestawu dokumentów, który nie zajmuje gigabajtów miejsca na dysku i który można zabrać ze sobą na dowolnym urządzeniu — stacjonarnym lub przenośnym.

W tym celu włączyliśmy obsługę plików PDF dla spisu treści. Zadbaliśmy o to, aby plik PDF był aktualizowany wraz z zawartością w aktywnej witrynie, dzięki czemu zawsze masz dostęp do najnowszej wersji zawartości.

<img alt="screenshot16]()

Dokumentacja platformy Azure

Słyszeliśmy twoją opinię na temat fragmentacji i wyzwań związanych z doświadczeniem, więc jesteśmy dobrze na naszej drodze do migracji naszej dokumentacji technicznej platformy Azure z witryny azure.microsoft.com, MSDN i GitHub oraz skonsolidowania jej w witrynie https://docs.microsoft.com/azure/.

Nowa strona centrum platformy Azure

Zmieniliśmy również wygląd i działanie strony docelowej dla zawartości dotyczącej platformy Azure. Oto niektóre z najważniejszych funkcji:

• Karta Usługi, na której są wyświetlane usługi platformy Azure pogrupowane według kategorii.
• Karta Deweloper, na której jest wyświetlana cała zawartość dotycząca dokumentacji platformy Azure dla interfejsu API REST, zestawu Azure .NET SDK, zestawu Azure Java SDK, interfejsu Azure CLI i programu Azure PowerShell.
• Karta Architektura dla architektów i deweloperów, na której mogą uzyskiwać informacje na temat wzorców projektowych w skali chmury.

Nowa strona usług

Zadbaliśmy o to, aby strony docelowe były spójne i zawierały linki do najważniejszych zasobów, takich jak:

• Link Omówienie usługi.
• Samouczki Wprowadzenie dla wszystkich odpowiednich platform i języków programowania.
• Link do wszystkich samouczków wideo dla danej usługi.
• Linki do zawartości dotyczącej dokumentacji interfejsu API.
• Link do pobrania całej dokumentacji dla danej usługi.

Nowy spis treści

Przenosząc się do witryny docs.microsoft.com/azure, przy okazji zwiększamy też spójność nawigacji po spisie treści. Choć każda usługa ma unikatowe właściwości, teraz podczas poruszania się po witrynie będzie stosowana podobna nawigacja.

Udoskonalone kolorowanie

Dodaliśmy kolorowanie słów kluczowych i parametrów dla przykładów kodu interfejsu wiersza polecenia platformy Azure, aby ułatwić czytanie i zrozumienie kodu.

Ulepszenia dokumentacji

Jednym z najczęściej opisywanych przez użytkowników problemów było to, że zawartość dotycząca interfejsu API, wiersza polecenia i programu PowerShell nigdy nie była aktualna. Gdy tylko platforma Azure się zmieniała, starsze wersje ręcznych przepływów pracy przestawały działać.

W tej wersji zmieniliśmy systemy tak, aby odniesienia były tworzone bezpośrednio z kodu źródłowego. Wraz z dostarczaniem nowych kompilacji dostarczana będzie również nowa zawartość. Podobnie jak w przypadku współtworzenia zawartości Instrukcje możliwe będzie współtworzenie generowanej automatycznie części dokumentacji.

Wprowadzamy także standaryzację używania otwartej specyfikacji interfejsu API (znanej wcześniej jako Swagger) do opisywania interfejsów API REST, co umożliwi nam uzyskanie spójnej reprezentacji danych dla usług REST, których będzie można użyć na potrzeby dokumentacji oraz zestawów SDK klientów. W przyszłości będziemy mogli także dodać funkcje interaktywne do dokumentacji REST i przykładowych ładunków żądań/odpowiedzi.

W tej wersji włączyliśmy następujące elementy:

• Interfejs wiersza polecenia platformy Azure 2.0 (wersja zapoznawcza)
• Azure PowerShell
• Zestaw Azure Java SDK
• Zestaw Azure .NET SDK
• Interfejsy API REST platformy Azure

Dokumentacja programu Visual Studio 2017 RC

Przedstawiamy dokumentację programu Visual Studio zintegrowaną bezpośrednio z nową i zaktualizowaną witryną docs.microsoft.com.

Nowa strona centrum programu Visual Studio

Strona centrum Visual Studio zawiera najważniejsze linki do wprowadzenia do wersji Release Candidate programu Visual Studio 2017.

Obejmuje to samouczki Przewodnik instalacji, Co nowego i Wprowadzenie. Zlokalizowana zawartość będzie dostępna już wkrótce. Nowa zawartość będzie dotyczyć tematów takich jak refaktoryzacja, praca z kodem, który nie jest częścią projektu, debugowanie problemów z wydajnością, wskazówki dotyczące optymalizacji czasu uruchamiania programu Visual Studio, szczegółowe informacje na temat wszystkich nowych funkcji edytora dotyczących produktywności i nawigacji oraz innych tematów.

Teraz, gdy program Visual Studio obsługuje w pełni dostosowany proces instalacji instalujący tylko te składniki, których chcesz używać, możesz dowiedzieć się, jak to działa w przypadku poszczególnych projektów deweloperskich, niezależnie od tego, czy obciążenia robocze obejmują platformy ASP.NET, Azure, Python, czy Windows.

Dokumentacja platform ASP.NET i Entity Framework Core

Dokumentacja platform ASP.NET Core i Entity Framework Core została przeniesiona z witryny docs.asp.net i usługi GitHub.

Dokumentacja platform ASP.NET / Entity Framework

Ponieważ platformy ASP.NET Core i Entity Framework Core są projektami typu open source, zintegrowaliśmy ich kod źródłowy i komentarze po trzech ukośnikach, aby zbudować odpowiednią dokumentację interfejsu API. To oznacza, że interfejs API i dokumentacja zawsze będą zsynchronizowane i będzie to następowało automatycznie.

Dokumentacja języka C++

W odpowiedzi na wielokrotne prośby naszych klientów zrefaktoryzowaliśmy dokumentację języka C++. Ma ona teraz bardziej kompaktowy format i wymaga mniejszej liczby linków pomiędzy tematami. Teraz możesz znaleźć wszystkie dokumenty dotyczące składowych klas w tym samym temacie co klasy.

Ponadto możesz dowiedzieć się więcej na temat najnowszych zmian zgodności standardów języka C++ i nowych opcji kompilacji takich jak parametr /fastlink, skorzystać z nowych wskazówek dotyczących przenoszenia w celu udoskonalania kodu ze starszych wersji programu Visual Studio i dowiedzieć się, jak wypróbować nową obsługę kompilowania w systemie Linux za pomocą narzędzia gcc.

Dokumentacja programu SQL w systemie Linux

Program SQL Server w systemie Linux (część oprogramowania SQL Server vNext Customer Technical Preview 1) jest gotowy do wypróbowania! Strona centrum zawiera najważniejsze linki, w których omówiono różne tematy, począwszy od wprowadzenia, a skończywszy na zarządzaniu i programowaniu za pomocą programu SQL Server w systemie Linux. Zlokalizowana zawartość będzie dostępna już wkrótce.

Wnioski

Chętnie wprowadzimy jeszcze więcej funkcji do nowej witryny dokumentacji, aby zapewnić spójność środowiska z naszymi produktami i usługami. Ponieważ ty, użytkownik, jesteś najbardziej krytycznym elementem w procesie dokumentacji, zachęcamy do skontaktowania się z nami i przekazywania opinii na temat tego, jak możemy ulepszyć to środowisko dla Ciebie na Twitterze.