Bidra till .NET-dokumentationsdatabaserna

Artikel
10/04/2024

Tack för att du vill bidra till .NET-dokumentationen!

Det här dokumentet beskriver processen för att bidra till de artiklar och kodexempel som finns på webbplatsen för .NET-dokumentationen. Bidrag kan vara så enkla som att ett stavfel har rättats, eller så komplexa som att nya artiklar har skrivits.

.NET-dokumentationswebbplatsen skapas från flera lagringsplatser. Det här är bara några av dem:

Riktlinjer för bidrag

Vi uppskattar communitybidrag till dokumentationen. Följande lista visar några vägledande regler att tänka på när du bidrar till .NET-dokumentationen:

Överraska oss INTE med stora pull-begäranden. Skicka en fråga istället och starta en diskussion så att vi kan komma överens om en riktning innan du lägger ner en massa tid.
Inkludera inte exempelkod infogat i en artikel.
Använd ett kodfragmentprojekt med kod som ska bäddas in i artikeln.
FÖLJ dessa anvisningar och guiden röst och tonfall.
ANVÄNDmallfilen som utgångspunkt för arbetet.
SKAPA en separat förgrening innan du arbetar med artiklarna.
Följ GitHub-flödet.
Blogga och twittra gärna om dina bidrag!

Om du följer dessa riktlinjer får både du och vi en bättre upplevelse.

Bidragsprocess

Steg 1: Om du är intresserad av att skriva nytt innehåll eller noggrant revidera befintligt innehåll öppnar du ett problem som beskriver vad du vill göra. Innehållet i dokumentmappen är uppdelat i avsnitt som återspeglas i innehållsförteckningen (TOC). Definiera var i innehållsförteckningen ämnet kommer att finnas. Få feedback på ditt förslag.

-eller-

Välj en befintlig fråga eller ett befintligt problem och lös det. Du kan se vår lista med öppna frågor och anmäla dig som frivillig att arbeta med dem som du är intresserad av:

Filtrera efter den bra första problemetiketten för, ja, bra första problem.
Filtrera efter den hjälp som söks efter etiketten för problem som är lämpliga för community-bidrag. Den här typen av problem kräver vanligtvis minimal kontext.
Erfarna deltagare kan ta sig an vilka frågor och problem de vill.

När du hittar frågor eller problem som du vill arbeta med lägger du till en kommentar för att fråga om de är öppna.

När du har valt en uppgift att arbeta med skapar du ett GitHub-konto och går vidare till steg 2.

Steg 2: Förgrena /dotnet/docs lagringsplatsen (eller vilken lagringsplats du bidrar till) efter behov och skapa en gren för dina ändringar.

Små ändringar finns i Redigera i webbläsaren.

Steg 3: Gör ändringarna i denna nya förgrening.

Om det är ett nytt ämne kan du använda denna mallfil som utgångspunkt. Den innehåller skrivanvisningar och förklarar också vilka metadata som krävs för varje artikel, t.ex. författarinformation. Mer information om Markdown-syntaxen som används i Microsoft Learn-innehåll finns i Markdown-referens.

Navigera till mappen som motsvarar den TOC-plats som fastställs för din artikel i steg 1. Mappen innehåller Markdown-filer för alla artiklar i avsnittet. Om det behövs skapar du en ny mapp där du kan placera filerna för ditt innehåll. Huvudartikeln för avsnittet kallas index.md.

För bilder och andra statiska resurser skapar du en undermapp med namnet Media inuti mappen med artikeln, om den inte redan finns. I mappen Media skapar du en undermapp med artikelnamnet (förutom indexfilen). Mer information om var filerna ska placeras finns i avsnittet Exempelmappstruktur .

Inkludera inte kod infogad i artikeln, såvida du inte visar en konstruktion som inte kompileras. Använd i stället ett kodfragmentprojekt och inkludera koden med hjälp av kodtillägget. Det säkerställer att exempelkoden verifieras av vårt CI-system.

För kodfragment skapar du en undermapp med namnet snippets inuti mappen som innehåller artikeln, om den inte redan finns. Skapa en undermapp i mappen snippets och namnge det med samma namn som artikeln. Normalt har du kodfragment för alla tre av de viktigaste .NET-språken, dvs. C#, F# och Visual Basic. I så fall skapar du undermappar med namnen csharp, fsharp och vb för vart och ett av de tre projekten. Om du skapar ett kodfragment för en artikel i mappen docs/csharp, docs/fsharp eller docs/visual-basic kommer kodfragmentet endast att finnas på ett språk, så du kan utelämna undermappen för språk. Mer information om var filerna ska placeras finns i avsnittet Exempelmappstruktur .

Kodfragment är små, fokuserade kodexempel som demonstrerar begreppen som beskrivs i en artikel. Större program som är avsedda för nedladdning och utforskning bör sparas på lagringsplatsen dotNet/samples. Fullständiga exempel beskrivs i avsnittet Bidra till exempel.

Steg 4: Skicka en pull-begäran (PR) från din gren till standardgrenen.

Viktigt!

Funktionen för automatiska kommentarer är inte tillgänglig på någon av .NET-dokumentlagringsplatserna för närvarande. Medlemmar i teamet för .NET-dokumenten kommer att granska och sammanställa din pull-begäran.

Varje pr bör vanligtvis åtgärda ett problem i taget, såvida inte flera problem är relaterade till samma PR-korrigering. En pull-begäran kan ändra en eller flera filer. Om det gäller flera korrigeringar i olika filer, är det bäst att ha olika pull-begäranden.

Om din pr åtgärdar ett befintligt problem lägger du till nyckelordet i Fixes #Issue_Number PR-beskrivningen. Det innebär att ärendet stängs automatiskt när pull-begäran har sammanställts. Mer information finns i Länka en pull-begäran till ett problem med hjälp av ett nyckelord.

.NET-teamet granskar din pull-begäran och meddelar dig om det behövs fler uppdateringar/ändringar innan de kan godkänna den.

Steg 5: Gör eventuella nödvändiga uppdateringar på din förgrening efter diskussioner med teamet.

Underhållarna sammanfogar din pr till standardgrenen när feedbacken har tillämpats och ändringen har godkänts.

Vi skickar regelbundet alla incheckningar från standardgrenen till live-grenen och sedan kan du se ditt bidrag live i .NET-dokumentationen. Publicering sker vanligtvis varje arbetsdag.

Exempel på mappstruktur

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

Kommentar

Språkmapparna under kodfragment behövs inte i språkguideområdet, där endast ett språk antas. I C#-guiden antas det till exempel att alla kodfragment är C#.

Strukturen ovan innehåller en bild, portability_report.png, och tre kodprojekt med kodfragment som ingår i artikeln porting-overview.md.

Kodfragment/delad mapp används för kodfragment som kan omfatta flera artiklar i samma överordnade mapp, till exempel portningsmappen i föregående exempel. Använd endast den delade mappen när du har en specifik anledning att göra det, till exempel XAML-kod som refereras till av flera artiklar, men som inte kan kompileras i den artikelspecifika mappen.

Media kan också delas mellan artiklar när dessa artiklar finns i samma överordnade mapp, till exempel portningsmappen i föregående exempel. Den här delade mappen bör undvikas om möjligt och endast användas när det är meningsfullt. Det kan till exempel vara meningsfullt att dela en gemensam inläsningsskärm för appen som demonstreras eller dela Visual Studio-dialogrutor som återanvänds i flera artiklar.

Viktigt!

Av historiska skäl lagras många av kodfragmenten under mappen /samples på lagringsplatsen dotNet/dokument. Om du gör större ändringar i en artikel bör dessa kodfragment flyttas till den nya strukturen. Oroa dig dock inte för att flytta kodfragment för små ändringar.

Bidra till exempel

Vi gör följande åtskillnad för kod som stöder vårt innehåll:

Exempel: läsarna kan ladda ned och köra exemplen. Alla exempel ska vara fullständiga program eller bibliotek. När exemplet skapar ett bibliotek, ska det innehålla enhetstester eller ett program som innebär att läsarna kan köra koden. De använder ofta mer än en teknik, funktion eller verktygssats. Filen readme.md för varje exempel refererar till artikeln, så att du kan läsa mer om begreppen som finns i exemplen.
Kodfragment: avser ett mindre begrepp eller en mindre aktivitet. De kompileras, men de är inte avsedda att vara fullständiga program. De bör kunna köras korrekt, men är inte något programexempel för ett vanligt scenario. Istället är de utformade att vara så små som möjligt för att visa ett enda begrepp eller en enda funktion. De bör inte vara större än en enda kodskärm.

Exempel lagras på lagringsplatsen dotNet/samples. Vi strävar mot en modell där vår mappstruktur för exemplen matchar vår mappstruktur för dokument. Standarder som vi följer är:

Mappar på den översta nivån matchar mapparna på den översta nivån på lagringsplatsen docs. Dokumentlagringsplatsen innehåller mappen machine-learning/tutorials och exempel på självstudier för maskininlärning finns i mappen samples/machine-learning/tutorials.

Dessutom ska alla exempel i mapparna Core och Standard kunna skapas och köras på alla plattformar som stöds av .NET Core. Vårt CI-system tillämpar detta. Mappen Ramverk på översta nivån innehåller exempel som endast skapas och valideras i Windows.

Projektexempel bör kunna skapas och köras på bredast möjliga plattformsuppsättning för exemplet. Det innebär i praktiken att man skapar .NET Core-baserade konsolprogram när det är möjligt. Exempel som är specifika för webben eller ett UI-ramverk bör kunna lägga till dessa verktyg efter behov. Exemplen innefattar webbappar, mobilappar, WPF- eller WinForms-appar osv.

Vi strävar mot att ha ett CI-system för all kod. När du uppdaterar exempel bör du se till att varje uppdatering ingår i ett byggbart projekt. Det idealiska är att lägga till tester även för exempel för att se att de stämmer.

Varje fullständigt exempel som du skapar ska innehålla filen readme.md. Filen ska innehålla en kort beskrivning av exemplet (ett eller två textstycken). Filen readme.md talar om för läsarna vad de kommer att lära sig när de utforskar exemplet. I filen readme.md ska det även finnas en länk till live-dokumentet på webbplatsen för .NET-dokumentationen. Om du bestämma var en viss fil på lagringsplatsen ska mappas till webbplatsen, byter du /docs i lagringsplatsens sökväg mot https://learn.microsoft.com/dotnet.

Ämnet kommer också att innehålla länkar till exemplet. Länka direkt till exemplets mapp på GitHub.

Skriv ett nytt exempel

Exempel är fullständiga program och bibliotek som är avsedda att laddas ned. De kan vara små, men de demonstrerar koncept på ett sätt som gör det möjligt för användarna att utforska och experimentera på egen hand. Riktlinjerna för exempel förklarar hur användarna kan ladda ned och utforska dem. Utforska PLINQ-exemplen (Parallel LINQ) som ett exempel på de olika riktlinjerna.

Ditt exempel måste ingå i ett byggbart projekt. När det är möjligt ska projekten skapas för alla plattformar som stöds av .NET Core. Undantag från detta är exempel som visar en plattformsspecifik funktion eller ett plattformsspecifikt verktyg.
Ditt exempel bör överensstämma med körningskodningsformatet för att upprätthålla konsekvens.

Dessutom föredrar vi användningen av static-metoder istället för instansmetoder, när man visar något som inte kräver att man skapar en instans av ett nytt objekt.
Exemplet bör innehålla lämplig undantagshantering. Det bör hantera alla undantag som kan inträffa i exemplets sammanhang. Ett exempel som anropar Console.ReadLine-metoden för att hämta användarindata, bör exempelvis använda lämplig undantagshantering när en indatasträng skickas som ett argument till en metod. På liknande sätt måste resulterande undantag hanteras om ditt exempel förväntar sig att ett metodanrop kan misslyckas. Hantera alltid de specifika undantag som utlöses av metoden, istället för grundklassundantag som Exception eller SystemException.

Skapa ett exempel:

Registrera ett ärende eller lägg till en kommentar till ett befintligt ärende om att du arbetar med det.
Skriv ett ämne som förklarar begreppen som visas i exemplet (exempel: docs/standard/linq/where-clause.md).
Skriv exemplet (exempel: WhereClause-Sample1.cs).

Skapa en Program.cs med en huvudstartpunkt som anropar dina exempel. Om det redan finns ett, lägger du till anropet i ditt exempel:

public class Program
{
    public void Main(string[] args)
    {
        WhereClause1.QuerySyntaxExample();

        // Add the method syntax as an example.
        WhereClause1.MethodSyntaxExample();
    }
}

Du skapar ett .NET-kodfragment eller exempel med hjälp av .NET CLI, som kan installeras med .NET SDK. Så här skapar och kör du ditt exempel:

Gå till exempelmappen och kontrollera om det finns några fel:
```
dotnet build
```
Kör ditt exempel:
```
dotnet run
```
Lägg till en readme.md i rotkatalogen för ditt exempel.

Den ska innehålla en kort beskrivning av koden och ge personer som läser artikeln en referens till exemplet. Början av readme.md måste innehålla de metadata som krävs för webbläsaren för exemplen. Blocket för sidhuvudet ska innehålla följande fält:
```
---
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
---
```
- Samlingen languages bör endast innehålla de språk som är tillgängliga för exemplet.
- Samlingen products bör endast innehålla de produkter som är relevanta för ditt exempel.

Förutom där det anges skapas alla exempel från kommandoraden på alla plattformar som stöds av .NET. Det finns några exempel som är specifika för Visual Studio och som kräver Visual Studio 2017 eller senare. Dessutom visar vissa exempel plattformsspecifika funktioner och kräver en specifik plattform. Andra exempel och kodfragment kräver .NET Framework och kommer att köras på Windows-plattformar. De måste därför ha Developer Pack för målversionen av Framework.

Den interaktiva C#-upplevelsen

Alla kodfragment som ingår i en artikel använder en språktagg för att ange källspråket. Korta kodfragment i C# kan använda språktaggen csharp-interactive för att ange ett C#-kodfragment som körs i webbläsaren. (Infogade kodfragment använder taggen csharp-interactive för kodfragment som ingår från källan och använder taggen code-csharp-interactive .) Dessa kodfragment visar ett kodfönster och ett utdatafönster i artikeln. Utdatafönstret visar alla utdata från körningen av den interaktiva koden när användaren har kört kodfragmentet.

Den interaktiva C#-upplevelsen ändrar hur vi arbetar med kodfragment. Besökare kan köra kodfragmentet för att se resultatet. Ett antal faktorer hjälper dig att avgöra om kodfragmentet eller motsvarande text ska innehålla information om utdata.

När du ska visa förväntade utdata utan att köra kodfragmentet

Artiklar för nybörjare bör innehålla utdata så att läsarna kan jämföra utdata från sitt arbete med det förväntade svaret.
Kodfragment där utdata är integrerade i ämnet bör visa dessa utdata. Artiklar om formaterad text bör till exempel visa textformatet utan att köra kodfragmentet.
När både kodfragmentet och de förväntade utdata är korta bör du överväga att visa utdata. Det sparar tid.
Artiklar som beskriver hur aktuell kultur eller invariant kultur påverkar dina utdata bör förklara dina förväntade utdata. En interaktiv REPL (Read Evaluate Print Loop) körs på en Linux-baserad värd. Standardkulturen och den invarianta kulturen skapar olika utdata i olika operativsystem och datorer. Artikeln bör förklara dina utdata i Windows-, Linux -och Mac-system.

När förväntade utdata ska undantas från kodfragmentet

Artiklar där kodfragmentet genererar större utdata bör inte innehålla det i kommentarer. Det döljer koden när kodfragmentet har körts.
Artiklar där kodfragmentet visar ett ämne, men utdata är inte integrerade för att förstå det. Det kan exempelvis vara kod som kör en LINQ-fråga för att förklara en frågesyntax och som sedan visar varje objekt i utdatasamlingen.

Kommentar

Du kanske lägger märke till att vissa av ämnena inte följer alla riktlinjer som har visats här. Vi strävar mot att uppnå samstämmighet på hela webbplatsen. Se listan med öppna ärenden där vi arbetar mot det specifika målet.

Bidra till icke-engelskt innehåll

Bidrag till maskinöversatt innehåll (MT) godkänns för närvarande inte. För att förbättra kvaliteten på maskinöversatt innehåll har vi gått över till en neural MT-motor. Vi accepterar och uppmuntrar bidrag för mänskligt översatt innehåll (HT) som används för att träna den neurala MT-motorn. Med tiden kommer bidragen till HT-innehåll att förbättra kvaliteten på både HT och MT. MT-ämnen kommer att ha en friskrivning som anger att en del av ämnet kan vara maskinöversatt och knappen Redigera visas inte, eftersom redigering är inaktiverat.

Kommentar

De flesta lokaliserade dokumentationen ger inte möjlighet att redigera eller ge feedback via GitHub. Om du vill ge feedback om lokaliserat innehåll använder du https://aka.ms/provide-feedback formuläret.

Licensavtal för deltagare

Du måste signera .NET Foundations licensavtal för bidrag innan din pull-begäran sammanställs. Det är ett engångskrav för projekt i .NET Foundation. Du kan läsa mer om licensavtal för bidrag på Wikipedia.

Avtalet: LICENSavtal för .NET Foundation-deltagare (CLA)

Du behöver inte signera avtalet direkt. Du kan klona, förgrena och skicka din pull-begäran som vanligt. När din pull-begäran skapas klassificeras den av en CLA-robot. Om ändringen är liten (till exempel om du har rättat ett stavfel), märks din pull-begäran med cla-not-required. Annars klassificeras den som cla-required. När du har signerat licensavtalet för bidrag, kommer aktuella och kommande pull-begäranden att märkas som cla-signed.

Dela via

Bidra till .NET-dokumentationsdatabaserna

Riktlinjer för bidrag

Bidragsprocess

Exempel på mappstruktur

Bidra till exempel

Skriv ett nytt exempel

Den interaktiva C#-upplevelsen

När du ska visa förväntade utdata utan att köra kodfragmentet

När förväntade utdata ska undantas från kodfragmentet

Bidra till icke-engelskt innehåll

Licensavtal för deltagare

Feedback

Ytterligare resurser