Współtworzenie repozytoriów dokumentacji platformy .NET

Dziękujemy za zainteresowanie współtworzeniem dokumentacji platformy .NET.

Ten dokument opisuje proces współtworzenia artykułów i przykładów kodu hostowanych w witrynie dokumentacji platformy .NET. Współtworzyć można na różne sposoby, od poprawiania literówek po pisanie nowych artykułów.

Witryna dokumentacji platformy .NET jest tworzona na podstawie wielu repozytoriów. Są to tylko niektóre z nich:

• Artykuły koncepcyjne i fragmenty kodu dotyczące platformy .NET
• Przykłady i fragmenty kodu
• Dokumentacja interfejsów API platformy .NET
• Dokumentacja zestawu .NET Compiler Platform SDK
• Dokumentacja interfejsów API ML.NET

Wytyczne dotyczące współtworzenia

Doceniamy wkład społeczności w dokumentację. Na poniższej liście przedstawiono pewne wskazówki, które należy wziąć pod uwagę podczas współtworzenia dokumentacji platformy .NET:

• NIE ZASKAKUJ NAS dużymi żądaniami ściągnięcia. Zamiast tego zgłoś problem i rozpocznij dyskusję, abyśmy uzgodnili kierunek zanim zainwestujesz dużo czasu.
• Nie dołączaj przykładowego kodu wbudowanego w artykule.
• Do użycia projektu fragmentu kodu z kodem, który ma zostać osadzony w artykule.
• PRZESTRZEGAJ tych instrukcji oraz wytycznych dotyczących stron czasowników i tonu.
• UŻYWAJ pliku szablonu jako punktu początkowego w swojej pracy.
• UTWÓRZ oddzielną gałąź swojego rozwidlenia zanim zaczniesz pracę przy artykułach.
• POSTĘPUJ zgodnie z przepływem pracy usługi GitHub.
• PISZ bloga i tweety (lub coś innego) o swoim wkładzie, jeśli chcesz!

Stosowanie tych wytycznych zapewni Ci i nam lepszą płaszczyznę współpracy.

Proces współtworzenia

Krok 1. Jeśli interesuje Cię pisanie nowej zawartości lub gruntowna zmiana istniejącej zawartości, otwórz problem opisujący, co chcesz zrobić. Zawartość w folderze docs jest zorganizowana w sekcje, które są odzwierciedlone w spisie treści. Określ, gdzie w spisie treści będzie się znajdował temat. Uzyskaj opinie na temat swojej propozycji.

— lub —

Wybierz istniejący problem i rozwiąż go. Możesz przejrzeć naszą listę otwartych problemów i zgłosić się na ochotnika do pracy przy tych, które Cię interesują:

• Odfiltruj według etykiety dobrego pierwszego problemu, dobrze, dobre pierwsze problemy.
• Filtruj według etykiety żądanej pomocy pod kątem problemów odpowiednich do współtworzenia przez społeczność. Te problemy zazwyczaj wymagają minimalnego kontekstu.
• Doświadczeni współautorzy mogą zająć się dowolnymi problemami.

Jeśli znajdziesz problem, nad którym chcesz pracować, dodaj komentarz, aby zapytać, czy jest otwarty.

Po wybraniu zadania, nad którym chcesz pracować, utwórz konto usługi GitHub i przejdź do kroku 2.

Krok 2. Utwórz rozwidlenie /dotnet/docs repozytorium (lub niezależnie od tego, do którego repozytorium współtworzysz) w razie potrzeby i utwórz gałąź dla zmian.

Aby uzyskać niewielkie zmiany, zobacz Edytowanie w przeglądarce.

Krok 3. Wprowadzaj zmiany w tej nowej gałęzi.

Jeśli jest to nowy temat, jako punktu początkowego możesz użyć tego pliku szablonu. Zawiera on wytyczne dotyczące pisania, jak również objaśnia metadane wymagane dla każdego artykułu, takie jak informacje o autorze. Aby uzyskać więcej informacji na temat składni języka Markdown używanej w zawartości microsoft Learn, zobacz Dokumentacja języka Markdown.

Przejdź do folderu odpowiadającego lokalizacji spisu treści określonej dla artykułu w kroku 1. Ten folder zawiera pliki Markdown dla wszystkich artykułów w tej sekcji. W razie potrzeby utwórz nowy folder na pliki dla Twojej zawartości. Główny artykuł w tej sekcji nosi nazwę index.md.

W przypadku obrazów i innych zasobów statycznych utwórz podfolder o nazwie media wewnątrz folderu zawierającego Twój artykuł, jeśli jeszcze nie istnieje. Wewnątrz folderu media utwórz podfolder mający nazwę artykułu (z wyjątkiem pliku indeksu). Aby uzyskać więcej informacji na temat miejsca umieszczania plików, zobacz sekcję Przykładowa struktura folderów.

Nie dołączaj kodu w tekście do artykułu, chyba że demonstrujesz konstrukcję, która nie jest kompilowana. Zamiast tego użyj projektu fragmentów kodu i dołącz kod przy użyciu rozszerzenia kodu. Dzięki temu przykładowy kod jest weryfikowany przez nasz system ciągłej integracji.

W przypadku fragmentów kodu utwórz podfolder o nazwie snippets (fragmenty) wewnątrz folderu zawierającego Twój artykuł, jeśli jeszcze nie istnieje. W folderze snippets (fragmenty) utwórz podfolder o nazwie artykułu. W większości przypadków będziesz mieć fragmenty kodu dla wszystkich trzech głównych języków platformy .NET: C#, F# i Visual Basic. W takim przypadku należy utworzyć podfoldery o nazwach csharp, fsharp i vb dla każdego z trzech projektów. Jeśli tworzysz fragment kodu dla artykułu w folderze docs/csharp, docs/fsharp lub docs/visual-basic, fragment będzie tylko w jednym języku, więc możesz pominąć podfolder języka. Aby uzyskać więcej informacji na temat miejsca umieszczania plików, zobacz sekcję Przykładowa struktura folderów.

Fragmenty kodu to małe, skoncentrowane przykłady kodu, które demonstrują koncepcje omówione w artykule. Większe programy, przeznaczone do pobierania i eksploracji, powinny znajdować się w repozytorium dotnet/samples. Pełne przykłady zostały omówione w sekcji dotyczącej współtworzenia przykładów.

Krok 4. Przesyłanie żądania ściągnięcia z gałęzi do gałęzi domyślnej.

Ważne

Funkcjonalność automatyzacji komentarza jest teraz niedostępna w każdym z repozytoriów dokumentów platformy .NET. Członkowie zespołu dokumentacji platformy .NET sprawdzą i scalą Twoje żądanie ściągnięcia.

Każde żądanie ściągnięcia powinno zwykle rozwiązać jeden problem naraz, chyba że wiele problemów jest związanych z tą samą poprawką żądania ściągnięcia. Żądanie ściągnięcia może modyfikować jeden lub więcej plików. Jeśli wprowadzasz wiele poprawek do różnych plików, zalecane są różne żądania ściągnięcia.

Jeśli żądanie ściągnięcia rozwiąże istniejący problem, dodaj Fixes #Issue_Number słowo kluczowe do opisu żądania ściągnięcia. Dzięki temu problem zostanie automatycznie zamknięty po scaleniu żądania ściągnięcia. Aby uzyskać więcej informacji, zobacz Łączenie żądania ściągnięcia z problemem przy użyciu słowa kluczowego.

Zespół platformy .NET sprawdzi Twoje żądanie ściągnięcia i da Ci znać, czy do jego zatwierdzenia są konieczne jakiekolwiek inne aktualizacje/zmiany.

Krok 5. Wprowadź wszelkie niezbędne aktualizacje do swojej gałęzi w sposób omówiony z zespołem.

Osoby odpowiedzialne za żądanie ściągnięcia scalą żądanie ściągnięcia z gałęzią domyślną po zastosowaniu opinii i zatwierdzeniu zmiany.

Regularnie wypychamy wszystkie zatwierdzenia z gałęzi domyślnej do gałęzi dynamicznej, a następnie będziesz mieć możliwość wyświetlenia udziału na żywo w dokumentacji platformy .NET. W dni robocze zazwyczaj publikujemy codziennie.

Przykładowa struktura folderów

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
          portability_report.png
        /shared ...
      /snippets
        /porting-overview
          /csharp
            porting.csproj
            porting-overview.cs
            Program.cs
          /fsharp
            porting.fsproj
            porting-overview.fs
            Program.fs
          /vb
            porting.vbproj
            porting-overview.vb
            Program.vb
        /shared
          /csharp ...
          /fsharp ...
          /vb ...

Uwaga

Folderów języków w obszarze fragmentów kodu nie trzeba używać w obszarze przewodnika dotyczącego języków, jeśli założono użycie tylko jednego języka. Na przykład w przewodniku języka C# przyjęto założenie, że wszystkie fragmenty kodu to C#.

Pokazana powyżej struktura obejmuje jeden obraz, portability_report.png, oraz trzy projekty kodu, które zawierają fragmenty kodu zawarte w artykule porting-overview.md.

Fragmenty kodu/folder udostępniony są używane do fragmentów kodu, które mogą obejmować wiele artykułów w tym samym folderze nadrzędnym, takim jak folder przenoszenia w poprzednim przykładzie. Użyj folderu udostępnionego tylko wtedy, gdy masz określony powód, aby to zrobić, na przykład kod XAML, do którego odwołuje się wiele artykułów, ale nie można go skompilować w folderze specyficznym dla artykułu.

Multimedia mogą być również udostępniane w artykułach, gdy te artykuły znajdują się w tym samym folderze nadrzędnym, takim jak folder przenoszenia w poprzednim przykładzie. Ten folder udostępniony należy unikać, jeśli jest to możliwe, i używać go tylko wtedy, gdy ma to sens. Na przykład warto udostępnić wspólny ekran ładowania dla demonstrowanej aplikacji lub udostępnić okna dialogowe programu Visual Studio, które są ponownie używane w wielu artykułach.

Ważne

Z przyczyn historycznych wiele z uwzględnionych fragmentów kodu jest przechowywanych w folderze /samples w repozytorium dotnet/docs. W przypadku wprowadzania istotnych zmian w artykule te fragmenty kodu powinny zostać przeniesione do nowej struktury. Nie martw się jednak o przenoszenie fragmentów kodu dla małych zmian.

Współtworzenie przykładów

Wprowadzamy następujące rozróżnienie dla kodu obsługującego naszą zawartość:

• Przykłady: czytelnicy mogą pobrać i uruchomić przykłady. Wszystkie przykłady powinny być kompletnymi aplikacjami lub bibliotekami. Gdy przykład tworzy bibliotekę, powinien on zawierać testy jednostkowe lub aplikację, która umożliwi czytelnikom uruchomienie kodu. W przykładach często używana jest więcej niż jedna technologia, funkcja lub zestaw narzędzi. Plik readme.md dla każdego przykładu będzie odwoływał się do artykułu, co pozwoli przeczytać więcej na temat koncepcji objętej każdym przykładem.
• Fragmenty kodu: ilustrują mniejszą koncepcję lub zadanie. Można je skompilować, ale nie mają one być kompletnymi aplikacjami. Powinny się one poprawnie uruchomić, ale nie są przykładowymi aplikacjami dla typowego scenariusza. Zamiast tego są zaprojektowane tak, aby były jak najmniejsze w celu zilustrowania pojedynczej koncepcji lub funkcji. Nie powinny zajmować więcej niż jednego ekranu kodu.

Przykłady są przechowywane w repozytorium dotnet/samples. Pracujemy nad modelem, w którym struktura naszego folderu przykładów będzie pasować do struktury naszego folderu dokumentów. Do standardów, których przestrzegamy, należą:

• Foldery najwyższego poziomu są zgodne z folderami najwyższego poziomu w repozytorium docs. Na przykład w repozytorium docs jest folder machine-learning/tutorials, a przykłady dotyczące samouczków uczenia maszynowego są w folderze samples/machine-learning/tutorials.

Ponadto wszystkie przykłady w folderach core i standard powinny się skompilować i uruchomić na wszystkich platformach obsługiwanych przez platformę .NET Core. Nasz system kompilacji ciągłej integracji wymusi to. Folder najwyższego poziomu framework zawiera przykłady, które są kompilowane i weryfikowane tylko w systemie Windows.

Przykładowe projekty powinny umożliwiać kompilację i uruchomienie na najszerszym możliwym zestawie platform dla danego przykładu. W praktyce oznacza to kompilowanie aplikacji konsoli opartych na platformie .NET Core, gdzie to możliwe. Przykłady, które są specyficzne dla środowiska internetowego lub interfejsu użytkownika, powinny w razie potrzeby dodawać te narzędzia. Przykłady obejmują aplikacje internetowe, aplikacje mobilne, aplikacje WPF lub WinForms itd.

Pracujemy nad przygotowaniem systemu ciągłej integracji dla całego kodu. Gdy wprowadzasz jakiekolwiek aktualizacje do poprawek, upewnij się, że każda aktualizacja jest częścią projektu z możliwością kompilacji. Idealnie byłoby, gdyby do przykładów zostały również dodane poprawności.

Każdy kompletny przykład, który tworzysz, powinien zawierać plik readme.md. Ten plik powinien zawierać krótki opis przykładu (jeden lub dwa akapity). Plik readme.md powinien informować czytelników o tym, czego się dowiedzą, analizując ten przykład. Plik readme.md powinien też zawierać link do opublikowanego dokumentu w witrynie dokumentacji platformy .NET. Aby ustalić, gdzie dany plik w repozytorium jest zamapowany na daną witrynę, zastąp fragment /docs w ścieżce repozytorium fragmentem https://learn.microsoft.com/dotnet.

Twój temat będzie też zawierał linki do przykładu. Link powinien prowadzić bezpośrednio do folderu przykładu w usłudze GitHub.

Pisanie nowego przykładu

Przykłady to pełne programy i biblioteki przeznaczone do pobrania. Mogą mieć one niewielki zakres, ale pokazują koncepcje w sposób, który umożliwia użytkownikom samodzielne eksplorowanie i eksperymentowanie. Wskazówki dotyczące przykładów zapewniają możliwość pobrania i eksplorowania przez czytelników. Zapoznaj się z przykładami Parallel LINQ (PLINQ), aby poznać przykłady wszystkich wskazówek.

1. Twój przykład musi być częścią projektu z możliwością kompilacji. Gdzie to możliwe, projekty powinny dać się skompilować na wszystkich platformach obsługiwanych przez platformę .NET Core. Wyjątkiem są przykłady pokazujące specyficzną dla platformy funkcję lub narzędzie.

2. Twój przykład powinien być zgodny ze stylem kodowania środowiska uruchomieniowego, aby zachować spójność.

   Ponadto preferujemy stosowanie metod static zamiast metod wystąpień podczas prezentowania czegoś, co nie wymaga tworzenia wystąpień nowego obiektu.

3. Twój przykład powinien zawierać odpowiednią obsługę wyjątków. Powinien obsługiwać wszystkie wyjątki, które mogą być zgłaszane w kontekście tego przykładu. Przykładowo kod wywołujący metodę Console.ReadLine w celu pobrania danych wejściowych użytkownika powinien używać odpowiedniej obsługi wyjątków, gdy ciąg wejściowy jest przekazywany jako argument do metody. Analogicznie jeśli Twój przykład oczekuje niepowodzenia wywołania metody, wynikowy wyjątek musi zostać obsłużony. Zawsze należy obsługiwać konkretne wyjątki zgłaszane przez metodę, a nie wyjątki klasy bazowej, takie jak Exception lub SystemException.

Aby utworzyć przykład:

1. Zgłoś problem lub dodaj komentarz dotyczący istniejącego problemu, nad którym pracujesz.

2. Napisz temat, który objaśnia koncepcje przedstawiane w Twoim przykładzie (na przykład: docs/standard/linq/where-clause.md).

3. Napisz swój przykład (na przykład: WhereClause-Sample1.cs).

4. Za pomocą głównego punktu wejścia utwórz plik Program.cs, który wywołuje Twoje przykłady. Jeśli już istnieje, dodaj wywołanie to Twojego przykładu:

   public class Program
   {
       public void Main(string[] args)
       {
           WhereClause1.QuerySyntaxExample();
   
           // Add the method syntax as an example.
           WhereClause1.MethodSyntaxExample();
       }
   }
   

Możesz utworzyć dowolny fragment kodu platformy .NET lub przykład przy użyciu interfejsu wiersza polecenia platformy .NET, który można zainstalować za pomocą zestawu .NET SDK. Aby skompilować i uruchomić Twój przykład:

1. Przejdź do folderu przykładu i skompiluj go, aby sprawdzić, czy nie ma w nim błędów:

   dotnet build
   

2. Uruchom swój przykład:

   dotnet run
   

3. Dodaj plik readme.md do głównego katalogu Twojego przykładu.

   Powinien on zawierać krótki opis kodu i kierować czytelników do artykułu, który odwołuje się do przykładu. W górnej części pliku readme.md powinny znajdować się metadane wymagane przez przeglądarkę przykładów. Blok nagłówka powinien zawierać następujące pola:

   ---
   name: "really cool sample"
   description: "Learn everything about this really cool sample."
   page_type: sample
   languages:
     - csharp
     - fsharp
     - vbnet
   products:
     - dotnet-core
     - dotnet
     - dotnet-standard
     - aspnet
     - aspnet-core
     - ef-core
   ---
   

   • Kolekcja languages powinna zawierać tylko języki dostępne dla Twojego przykładu.
   • Kolekcja products powinna zawierać tylko produkty istotne dla Twojego przykładu.

Z wyjątkiem przypadków, w których zaznaczono, wszystkie przykłady są kompilowane z wiersza polecenia na dowolnej platformie obsługiwanej przez platformę .NET. Istnieje kilka przykładów specyficznych dla platformy Visual Studio i wymagających programu Visual Studio 2017 lub nowszego. Ponadto niektóre przykłady pokazują funkcje specyficzne dla platformy i będą wymagać konkretnej platformy. Inne przykłady i fragmenty kodu wymagają platformy .NET Framework i będą działać na platformach systemu Windows oraz będą potrzebować dodatku Developer Pack dla docelowej wersji platformy Framework.

Interaktywna platforma języka C#

Wszystkie fragmenty kodu zawarte w artykule używają tagu języka, aby wskazać język źródłowy. Krótkie fragmenty kodu w języku C# mogą używać tagu csharp-interactive języka do określania fragmentu kodu C#, który jest uruchamiany w przeglądarce. (Wstawki kodu wbudowanego używają tagu csharp-interactive , aby fragmenty kodu zawarte ze źródła używały tagu code-csharp-interactive ). Te fragmenty kodu zawierają okno kodu i okno danych wyjściowych w artykule. Okno danych wyjściowych wyświetla wszystkie dane wyjściowe z wykonywania kodu interaktywnego po uruchomieniu fragmentu kodu przez użytkownika.

Interaktywne środowisko języka C# zmienia sposób pracy z fragmentami kodu. Odwiedzający mogą uruchomić fragment kodu, aby wyświetlić wyniki. Wiele czynników pomaga określić, czy fragment kodu lub odpowiedni tekst powinien zawierać informacje o danych wyjściowych.

Kiedy wyświetlić oczekiwane dane wyjściowe bez uruchamiania fragmentu kodu

• Artykuły przeznaczone dla początkujących powinny udostępniać dane wyjściowe, aby czytelnicy mogli porównać dane wyjściowe swojej pracy z oczekiwaną odpowiedzią.
• Fragmenty kodu, w których dane wyjściowe są integralną częścią tematu, powinny wyświetlać te dane wyjściowe. Na przykład artykuły dotyczące sformatowanego tekstu powinny wyświetlać format tekstu bez uruchamiania fragmentu kodu.
• Gdy zarówno fragment kodu, jak i oczekiwane dane wyjściowe są krótkie, rozważ wyświetlenie danych wyjściowych. Zaoszczędzi to trochę czasu.
• Artykuły objaśniające, jak bieżąca kultura lub kultura niezmienna wpływają na dane wyjściowe, powinny objaśniać oczekiwane dane wyjściowe. Interaktywna pętla REPL (Read Evaluate Print Loop) działa na hostach opartych na systemie Linux. Domyślna kultura i kultura niezmienna tworzą inne dane wyjściowe dla różnych systemów operacyjnych i maszyn. Artykuł powinien objaśniać dane wyjściowe w systemach Windows, Linux i Mac.

Kiedy wykluczyć oczekiwane dane wyjściowe ze fragmentu kodu

• Artykuły, w których fragment kodu generuje większe dane wyjściowe, nie powinny zawierać ich w komentarzach. Zaciemnia kod po uruchomieniu fragmentu kodu.
• Artykuły, w których fragment kodu demonstruje temat, ale dane wyjściowe nie są integralną częścią jego zrozumienia. Na przykład kod uruchamiający zapytanie LINQ w celu wyjaśnienia składni zapytania, a następnie wyświetlający każdy element z kolekcji wyjściowej.

Uwaga

Możesz zauważyć, że niektóre tematy nie do końca przestrzegają wszystkich podanych tutaj wytycznych. Pracujemy nad osiągnięciem spójności w ramach witryny. Sprawdź listę otwartych problemów, które obecnie śledzimy, szukając tego określonego celu.

Współtworzenia zawartości innej niż angielska

Współtworzenie zawartości przetłumaczonej maszynowo nie jest obecnie możliwe. Aby zwiększyć jakość zawartości tłumaczonej maszynowo, wdrożyliśmy aparat neuronowego tłumaczenia maszynowego. Zachęcamy do współtworzenia zawartości przetłumaczonej przez ludzi, która służy do trenowania aparatu neuronowego tłumaczenia maszynowego. W miarę upływu czasu wkład w tworzenie zawartości tłumaczonej przez ludzi poprawi jakość zawartości tłumaczonej zarówno przez ludzi, jak i maszynowo. Tematy tłumaczone maszynowo będą zawierać zastrzeżenie informujące o tym, że część tematu może być tłumaczona maszynowo, a przycisk Edytuj nie będzie wyświetlany, ponieważ edytowanie jest wyłączone.

Uwaga

Większość zlokalizowanej dokumentacji nie oferuje możliwości edytowania ani przekazywania opinii za pośrednictwem usługi GitHub. Aby przekazać opinię na temat zlokalizowanej zawartości, użyj https://aka.ms/provide-feedback formularza.

Umowa licencyjna współautora

Zanim Twoje żądanie ściągnięcia zostanie scalone, musisz podpisać Umowę licencyjną współautora platformy .NET Foundation (CLA). Jest to jednorazowe wymaganie dla projektów na platformie .NET Foundation. Więcej na temat umów licencyjnych współautora (CLA) możesz przeczytać w Wikipedii.

Umowa: Umowa licencyjna współautora platformy .NET Foundation (CLA)

Nie musisz z góry podpisywać umowy. Możesz sklonować, rozwidlić i przekazać swoje żądanie ściągnięcia w zwykły sposób. Gdy Twoje żądanie ściągnięcia jest tworzone, jest ono klasyfikowane przez bota CLA. Jeśli zmiana jest mała (na przykład udało Ci się poprawić literówkę), wówczas żądanie ściągnięcia dostaje oznaczenie cla-not-required. W przeciwnym razie jest ono klasyfikowane jako cla-required. Po podpisaniu umowy CLA bieżące i wszystkie przyszłe żądania ściągnięcia będą oznaczone jako cla-signed.