Listopadowa aktualizacja witryny docs.microsoft.com

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

Z dumą ogłaszamy, że dokonaliśmy migracji dokumentacji dla platformy Azure, programu Visual Studio 2017 RC, języka C++, platformy ASP.NET Core, platformy Entity Framework Core i programu SQL w systemie Linux do witryny 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

Prostym ulepszeniem, które wprowadziliśmy na podstawie opinii użytkowników, jest podawanie szacowanego czasu czytania artykułu. Wiemy, że wiele osób poznaje i ocenia technologie podczas krótkich przerw między spotkaniami, dlatego podanie tego czasu zwiększa prawdopodobieństwo przeczytania artykułu.

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.

screenshot1

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.

screenshot2

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.

screenshot3 screenshot4

Notatki boczne i komentarze

Pytania, komentarze i opinie użytkowników są dla nas bardzo ważne. Nawiązaliśmy współpracę z firmą Livefyre, aby umożliwić dodawanie komentarzy i notatek bocznych do wszystkich naszych artykułów. W górnej części każdego artykułu zobaczysz opcję bezpośredniego przejścia 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.

screenshot5

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.

screenshot6

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.

screenshot7

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.

screenshot8

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.

screenshot9

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

screenshot10

Jasny/ciemny motyw

Dodaliśmy również selektor motywu, dzięki czemu można przełączać między jasnym i ciemnym motywem. Ta kwestia pojawiała się w opiniach w usłudze UserVoice.

screenshot12

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 nowym adresem URL.

Stary adres

https://technet.microsoft.com/pl-pl/library/dn646983.aspx

Nowy adres

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

Materiały przekazywane przez społeczność

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!

screenshot13

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ść.

screenshot14

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.

screenshot15

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

Dla klientów oznacza to, że dokumentacja powinna zawsze być zsynchronizowana z możliwościami interfejsu API, ponieważ istnieje teraz jedno źródło informacji dotyczące dokumentów i kodu. 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="zrzut_ekranu16]()

Dokumentacja platformy Azure

Posłuchaliśmy opinii użytkowników dotyczących fragmentacji i problemów ze środowiskiem, dlatego migrujemy dokumentację techniczną platformy Azure z witryn azure.microsoft.com, MSDN i GitHub do witryny 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:

screenshot17

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.
screenshot18

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.

screenshot19

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:

screenshot20 screenshot21

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 elementów członkowskich 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ż to użytkownik jest najważniejszym elementem procesu dokumentacji, zachęcamy wszystkich do kontaktu z nami za pośrednictwem usługi UserVoice lub Twitter i wyrażania opinii o tym, jak możemy udoskonalić to środowisko.