Bijdragen aan de .NET-documentatieopslagplaatsen

Bedankt voor uw interesse in het bijdragen aan de .NET-documentatie!

Dit document gaat over de procedure voor het bijdragen aan artikelen en codevoorbeelden die op de .NET-documentatiesite worden gehost. Bijdragen kunnen iets eenvoudigs betreffen als correcties van typfouten of iets ingewikkelds als nieuwe artikelen.

De .NET-documentatiesite is gebouwd op basis van meerdere opslagplaatsen. Dit zijn slechts enkele van deze:

• Conceptuele .NET-artikelen en codefragmenten
• Codevoorbeelden en -fragmenten
• .NET-API-referentie
• SDK-verwijzing .NET Compiler Platform
• API-verwijzing ML.NET

Richtlijnen voor bijdragen

We waarderen bijdragen van de community aan documentatie. De volgende lijst bevat enkele richtlijnen om rekening mee te houden wanneer u bijdraagt aan .NET-documentatie:

• NIET DOEN: verras ons niet met grote pull-aanvragen. In plaats daarvan kunt u beter een actie-item aanmaken, zodat we in gesprek kunnen gaan over de richting die we op moeten gaan voordat u hier erg veel tijd in gaat steken.
• Neem geen voorbeeldcode inline op in een artikel.
• Gebruik een codefragmentproject met code die in het artikel moet worden ingesloten.
• DOEN: volg deze instructies en de richtlijnen voor stijl en stem.
• DOEN: gebruik het sjabloonbestand als beginpunt van uw werk.
• DOEN: maak een aparte vertakking van uw fork voordat u aan de artikelen gaat werken.
• DOEN: volg de GitHub-stroom.
• DOEN: plaats regelmatig blogs en tweets (of wat u maar wilt) over uw bijdragen.

Volg deze richtlijnen zodat we allemaal een betere ervaring hebben.

Bijdrageproces

Stap 1: Als u geïnteresseerd bent in het schrijven van nieuwe inhoud of het grondig herzien van bestaande inhoud, opent u een probleem met een beschrijving van wat u wilt doen. De inhoud in de docs-map is ingedeeld in secties die worden weergegeven in de inhoudsopgave (Inhoudsopgave ). Definieer de locatie van het onderwerp in de inhoudsopgave. Krijg feedback over uw voorstel.

– of –

Kies een bestaand probleem en los het op. Of bekijk onze lijst met openstaande problemen en werk vrijwillig aan een van de actie-items waarin u geïnteresseerd bent:

• Filter op het goede label voor het eerste probleem voor, nou ja, goede eerste problemen.
• Filter op het gewenste label voor problemen die geschikt zijn voor de bijdrage van de community. Deze problemen vereisen doorgaans minimale context.
• Ervaren inzenders kunnen elk probleem aanpakken.

Wanneer u een dergelijk probleem vindt, voegt u een opmerking toe om te vragen of dit probleem openstaat.

Zodra u een taak hebt gekozen waaraan u wilt werken, maakt u een GitHub-account en gaat u verder met stap 2.

Stap 2: Fork de /dotnet/docs opslagplaats (of de opslagplaats waaraan u bijdraagt) indien nodig en maak een vertakking voor uw wijzigingen.

Zie Bewerken in de browser voor kleine wijzigingen.

Stap 3: breng de wijzigingen in deze nieuwe vertakking aan.

Als het een nieuw onderwerp is, kunt u dit sjabloonbestand als beginpunt gebruiken. Dit bestand bevat de schrijfrichtlijnen en uitleg over de metagegevens die voor elk artikel zijn vereist, zoals informatie over de auteur. Zie de Markdown-verwijzing voor meer informatie over de Markdown-syntaxis die wordt gebruikt in Microsoft Learn-inhoud.

Navigeer naar de map die overeenkomt met de locatie van de toc die is bepaald voor uw artikel in stap 1. Die map bevat de Markdown-bestanden voor alle artikelen in dat hoofdstuk. Maak indien nodig een nieuwe map waarin u de bestanden voor uw inhoud plaatst. Het hoofdartikel voor dat hoofdstuk heet index.md.

Voor afbeeldingen en andere statische resources maakt u de submap media in de map waarin uw artikel staat, als deze submap nog niet is gemaakt. Maak in de map media een submap met de naam van het artikel (met uitzondering van het indexbestand). Zie de sectie Voorbeeldmapstructuur voor meer informatie over waar u uw bestanden kunt plaatsen.

Voeg in het artikel geen code inline toe, tenzij u een constructie demonstreert die niet wordt gecompileerd. Gebruik in plaats daarvan een codefragmentproject en voeg de code toe met behulp van de code-extensie. Dit zorgt ervoor dat uw voorbeeldcode wordt gevalideerd door ons CI-systeem.

Maak voor codefragmenten een submap met de naam fragmenten in de map met uw artikel als deze submap nog niet bestaat. Maak in de map fragmenten een submap met de artikelnaam. In de meeste gevallen hebt u codefragmenten voor alle drie de belangrijkste .NET-talen: C#, F# en Visual Basic. Maak in dat geval submappen met de naam csharp, fsharpen vb voor elk van de drie projecten. Als u een fragment maakt voor een artikel onder de mappen docs/csharp, docs/fsharp of docs/visual-basic, is het fragment slechts in één taal, zodat u de taalsubmap kunt weglaten. Zie de sectie Voorbeeldmapstructuur voor meer informatie over waar u uw bestanden kunt plaatsen.

Codefragmenten zijn kleine, gerichte codevoorbeelden die de concepten demonstreren die in een artikel worden besproken. Grotere programma's, bedoeld voor downloaden en verkennen, moeten zich in de opslagplaats dotnet/samples bevinden. In de sectie Bijdragen aan voorbeelden zijn volledige voorbeelden opgenomen.

Stap 4: Dien een pull-aanvraag (PR) van uw vertakking in naar de standaardbranch.

Belangrijk

De functionaliteit automatisering van commentaar is op dit moment in geen enkele .NET-documentenopslagplaats beschikbaar. Leden van het .NET-documententeam zullen uw pull-aanvraag beoordelen en samenvoegen.

Elke pull-aanvraag moet meestal één probleem tegelijk oplossen, tenzij er meerdere problemen zijn gerelateerd aan dezelfde pull-aanvraagoplossing. Met de aanvraag kunnen een of meerdere bestanden worden aangepast. Als u oplossingen van meerdere problemen in verschillende bestanden wilt aanpakken, kunt u beter afzonderlijke pull-aanvragen gebruiken.

Als uw pull-aanvraag een bestaand probleem oplost, voegt u het Fixes #Issue_Number trefwoord toe aan de beschrijving van de pull-aanvraag. Op die manier wordt het actie-item automatisch afgesloten zodra de pull-aanvraag is samengevoegd. Zie Een pull-aanvraag koppelen aan een probleem met behulp van een trefwoord voor meer informatie.

Het .NET-team beoordeelt uw pull-aanvraag en laat u weten of er andere updates/wijzigingen nodig zijn voor de goedkeuring.

Stap 5: voer eventuele benodigde updates aan uw vertakking door die u met het team hebt besproken.

De onderhouders voegen uw pull-aanvraag samen in de standaardbranch zodra feedback is toegepast en uw wijziging is goedgekeurd.

We pushen regelmatig alle doorvoeringen van de standaardbranch naar de live-vertakking en vervolgens kunt u uw bijdrage live zien in de .NET-documentatie. Normaalgesproken publiceren we deze elke werkdag.

Voorbeeld van mapstructuur

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

Notitie

De taalmappen onder snippets zijn niet nodig in het gedeelte van het taalgebied. Daar wordt uitgegaan van één taal. In de C#-handleiding wordt bijvoorbeeld ervan uitgegaan dat alle fragmenten C# zijn.

De structuur die hierboven wordt weergegeven, bevat één afbeelding, portability_report.png, en drie codeprojecten die codefragmenten uit het artikel porting-overview.md bevatten.

De fragmenten/gedeelde map worden gebruikt voor fragmenten die meerdere artikelen in dezelfde bovenliggende map kunnen omvatten, zoals de overdrachtsmap in het vorige voorbeeld. Gebruik de gedeelde map alleen als u een specifieke reden hebt om dit te doen, zoals XAML-code waarnaar wordt verwezen door meerdere artikelen, maar deze kan nog niet worden gecompileerd in de artikelspecifieke map.

Media kunnen ook worden gedeeld tussen artikelen wanneer deze artikelen zich in dezelfde bovenliggende map bevinden, zoals de overdrachtsmap in het vorige voorbeeld. Deze gedeelde map moet indien mogelijk worden vermeden en alleen worden gebruikt wanneer dit zinvol is. Het kan bijvoorbeeld zinvol zijn om een gemeenschappelijk laadscherm te delen voor de app die wordt gedemonstreerd of Visual Studio-dialoogvensters te delen die opnieuw worden gebruikt in meerdere artikelen.

Belangrijk

Om historische redenen zijn veel van de opgenomen fragmenten opgeslagen in de map /samples in de opslagplaats dotnet/docs. Als u belangrijke wijzigingen in een artikel aanbrengt, moeten deze fragmenten naar de nieuwe structuur worden verplaatst. U hoeft zich echter geen zorgen te maken over het verplaatsen van fragmenten voor kleine wijzigingen.

Bijdragen aan voorbeelden

We maken het volgende onderscheid voor code die in onze inhoud ondersteunt:

• Voorbeelden: lezers kunnen de voorbeelden downloaden en uitvoeren. Alle voorbeelden moeten volledige toepassingen of bibliotheken zijn. In het geval het voorbeeld een bibliotheek maakt, moet deze eenheidstesten of een toepassing bevatten waarmee lezers de code kunnen uitvoeren. Vaak wordt meer dan één technologie, functie of toolkit gebruikt. Het readme.md-bestand voor elk voorbeeld verwijst naar het artikel zodat u meer kunt lezen over de concepten die in de voorbeelden worden gegeven.
• Codefragmenten: hiermee geeft u uitleg over een kleiner concept of een kleinere taak. U kunt ermee compileren, maar ze zijn niet bedoeld om als complete toepassing te gebruiken. Ze moeten wel op de goede manier worden uitgevoerd, maar ze zijn geen voorbeeldtoepassing voor een typisch scenario. In plaats daarvan zijn ze ontworpen om zo klein mogelijk te zijn om één concept of functie uit te leggen. Deze fragmenten moeten niet langer zijn dan één scherm met code.

De voorbeelden bevinden zich in de opslagplaats dotnet/samples. We werken aan de ontwikkeling van een model waarin de structuur van onze map met voorbeelden overeenkomt met de structuur van onze map met documenten. We volgen de volgende standaarden:

• Mappen op het hoogste niveau komen overeen met de mappen op het hoogste niveau in de opslagplaats documenten. De opslagplaats Documenten bevat bijvoorbeeld de map machine learning/zelfstudies en de voorbeelden voor zelfstudies over machine learning bevinden zich in de map voorbeelden/machine learning/zelfstudies.

Daarnaast moeten alle voorbeelden in de mappen kern en standaard worden ontwikkeld en uitgevoerd op alle platformen die door .NET Core worden ondersteund. Dit zal door ons CI-ontwikkelingssysteem worden afgedwongen. De map framework op het hoogste niveau bevat voorbeelden die alleen in Windows worden ontwikkeld en gevalideerd.

Voorbeeldprojecten moeten worden ontwikkeld en uitgevoerd op de breedste set platformen die voor het gegeven voorbeeld mogelijk is. In de praktijk betekent dit dat u waar mogelijk consoletoepassingen op basis van .NET Core moet ontwikkelen. Voor voorbeelden die specifiek zijn voor internet of een UI-framework moeten die hulpprogramma's waar nodig worden toegevoegd. Voorbeelden zijn bijvoorbeeld webtoepassingen, mobiele apps, WPF of WinForms-apps.

We werken aan de ontwikkeling van een CI-systeem voor alle code. Wanneer u voorbeelden bijwerkt, moet u ervoor zorgen dat elke update deel uitmaakt van een project dat kan worden ontwikkeld. U kunt het beste ook testen toevoegen om te controleren of de voorbeelden correct zijn.

Elk volledige voorbeeld dat u maakt, moet een readme.md-bestand bevatten. Dit bestand moet een korte beschrijving van het voorbeeld (van 1 à 2 paragrafen) bevatten. Uit het readme.md-bestand moeten lezers kunnen opmaken wat ze gaan leren wanneer ze dit voorbeeld verkennen. In het readme.md-bestand moet ook een koppeling naar het live-document op de .NET-documentatiesite staan. Vervang /docs in het pad van de opslagplaats door https://learn.microsoft.com/dotnet om te bepalen op welke locatie een bepaald bestand in de opslagplaats aan die site wordt toegewezen.

Uw onderwerp bevat ook koppelingen naar het voorbeeld. Geef een directe koppeling op naar de map van het voorbeeld op GitHub.

Een nieuw voorbeeld schrijven

Voorbeelden zijn volledige programma's en bibliotheken die zijn bedoeld om te worden gedownload. Ze zijn mogelijk klein in omvang, maar illustreren concepten op een manier waarop mensen hun eigen programma’s kunnen verkennen en experimenteren. De richtlijnen voor voorbeelden zorgen dat lezers ze kunnen downloaden en verkennen. Bekijk de Parallel LINQ-voorbeelden (PLINQ) als voorbeeld van elk van de richtlijnen.

1. Uw voorbeeld moet deel uitmaken van een project dat kan worden ontwikkeld. De projecten moeten waar mogelijk worden ontwikkeld op alle platformen die door .NET Core worden ondersteund, met uitzondering van voorbeelden die functies of hulpprogramma's aangeven die specifiek bij een platform horen.

2. Uw voorbeeld moet voldoen aan de runtimecoderingsstijl om consistentie te behouden.

   Daarnaast kunt u beter static-methoden gebruiken in plaats van de instantiemethoden wanneer u iets wilt tonen waarvoor het niet nodig is om een nieuw object te instantiëren.

3. Uw voorbeeld moet over de juiste verwerking van uitzonderingen beschikken. Alle uitzonderingen moeten kunnen worden verwerkt die zich in de context van het voorbeeld kunnen voordoen. Een voorbeeld waarmee bijvoorbeeld de methode Console.ReadLine wordt aangeroepen om gebruikersinvoer op te halen, moet de juiste verwerking van uitzonderingen gebruiken wanneer een ingevoerde tekenreeks als argument naar een methode wordt doorgestuurd. Als uw voorbeeld verwacht dat een methode-aanroep zal mislukken, moet de resulterende uitzondering ook worden verwerkt. Verwerk altijd de specifieke uitzonderingen die de methode opwerpt en niet de uitzonderingen uit de basisklasse zoals Exception of SystemException.

U maakt als volgt een voorbeeld:

1. Meld een actie-item aan of voeg commentaar toe aan een bestaand actie-item waaraan u werkt.

2. Schrijf het onderwerp waarin de concepten worden uitgelegd die in uw voorbeeld worden aangegeven (bijvoorbeeld: docs/standard/linq/where-clause.md).

3. Schrijf uw voorbeeld (voorbeeld: WhereClause-Sample1.cs).

4. Maak een Program.cs met een hoofdinvoerpunt waardoor uw voorbeelden worden aangeroepen. Als er al een aanroep bestaat, voegt u deze aan uw voorbeeld toe:

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

U bouwt een .NET-fragment of -voorbeeld met behulp van de .NET CLI, die kan worden geïnstalleerd met de .NET SDK. U kunt uw voorbeeld als volgt bouwen en uitvoeren:

1. Ga naar de map met voorbeelden en bouw uw voorbeeld om op fouten te controleren:

   dotnet build
   

2. Voer uw voorbeeld uit:

   dotnet run
   

3. Voeg een readme.md-bestand toe aan de hoofdmap van uw voorbeeld.

   Dit bestand moet een korte beschrijving van de code bevatten en mensen verwijzen naar het artikel waarin het voorbeeld wordt genoemd. De bovenkant van readme.md moet de metagegevens bevatten die nodig zijn voor de voorbeeldenbrowser. Het headerblok moet de volgende velden bevatten:

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

   • De verzameling languages moet alleen de talen bevatten die beschikbaar zijn voor uw voorbeeld.
   • De verzameling products moet alleen de producten bevatten die relevant zijn voor uw voorbeeld.

Behalve waar vermeld, bouwen alle voorbeelden vanaf de opdrachtregel op elk platform dat wordt ondersteund door .NET. Er zijn een aantal voorbeelden die specifiek bedoeld zijn voor Visual Studio en waarvoor Visual Studio 2017 of hoger is vereist. Daarnaast bevatten enkele voorbeelden platformspecifieke functies. Hiervoor is het specifieke platform vereist. Voor andere voorbeelden en codefragmenten is het .NET Framework vereist. Deze worden uitgevoerd op Windows-platformen en hiervoor is het Developer Pack voor de beoogde Framework-versie vereist.

De interactieve C#-ervaring

Alle fragmenten in een artikel gebruiken een taaltag om de brontaal aan te geven. Korte codefragmenten in C# kunnen de csharp-interactive taaltag gebruiken om een C#-fragment op te geven dat in de browser wordt uitgevoerd. (Inline-codefragmenten gebruiken de csharp-interactive tag voor fragmenten uit de bron, gebruik de code-csharp-interactive tag.) Deze codefragmenten geven een codevenster en een uitvoervenster in het artikel weer. In het uitvoervenster wordt uitvoer weergegeven van het uitvoeren van de interactieve code zodra de gebruiker het codefragment heeft uitgevoerd.

De interactieve C#-ervaring verandert de werking van codefragmenten. Bezoekers kunnen het fragment uitvoeren om de resultaten te bekijken. Een aantal factoren helpen bepalen of het codefragment of de bijbehorende tekst informatie over de uitvoer moet bevatten.

Wanneer wordt de verwachte uitvoer weergegeven zonder het fragment uit te voeren

• Artikelen die voor beginners zijn bedoeld, moet uitvoer geven zodat lezers de uitvoer van hun werk kunnen vergelijken met het verwachte antwoord.
• Fragmenten waarin de uitvoer integraal is voor het onderwerp, moet die uitvoer weergeven. Artikelen over opgemaakte tekst moeten bijvoorbeeld de tekstopmaak weergeven zonder het fragment uit te voeren.
• Wanneer zowel het fragment als de verwachte uitvoer kort is, kunt u overwegen de uitvoer weer te geven. Dit bespaart wat tijd.
• In artikelen waarin wordt uitgelegd hoe de huidige cultuur of niet-variabele cultuur invloed heeft op de uitvoer, moet de verwachte uitvoer worden verklaard. De interactieve REPL (de lus tussen lezen, evalueren en afdrukken) wordt uitgevoerd op een host op basis van Linux. De standaardcultuur en de niet-variabele cultuur produceren verschillende uitvoer op verschillende besturingssystemen en computers. In het artikel moet de uitvoer in Windows-, Linux- en Mac-systemen worden uitgelegd.

Wanneer moet de verwachte uitvoer van het fragment worden uitgesloten

• Artikelen waarin het fragment een grotere uitvoer genereert, mag dat niet opnemen in opmerkingen. De code wordt verborgen zodra het codefragment is uitgevoerd.
• Artikelen waarin het codefragment een onderwerp demonstreert, maar de uitvoer is niet integraal om het te begrijpen. Code waarmee bijvoorbeeld een LINQ-query wordt uitgevoerd om de querysyntaxis uit te leggen en vervolgens elk item in de uitvoerverzameling weer te geven.

Notitie

U merkt wellicht dat een in aantal onderwerpen op dit moment niet alle richtlijnen worden gevolgd die hierin zijn opgegeven. We werken aan consistentie voor de hele site. Controleer de lijst met openstaande actie-items die we momenteel voor dat specifieke doel volgen.

Bijdragen aan niet-Engelse inhoud

Bijdragen voor inhoud die is vertaald met behulp van machinevertaling (MT; Machine Translation), worden momenteel niet geaccepteerd. Om de kwaliteit van MT-inhoud te verbeteren, zijn we overgegaan naar een engine voor neurale machinevertaling (NMT; Neural MT). We accepteren en stimuleren bijdragen voor door de mensen vertaalde inhoud (HT; Human Translated), die wordt gebruikt voor het trainen van de engine voor neurale machinevertaling. Na verloop van tijd kunnen bijdragen aan HT-inhoud de kwaliteit van zowel HT als MT verbeteren. Onderwerpen waarop MT is toegepast, bevatten een disclaimer waarin wordt aangegeven dat delen van het onderwerp MT-inhoud kunnen bevatten. Tevens is de knop Bewerken niet beschikbaar omdat bewerken is uitgeschakeld.

Notitie

De meeste gelokaliseerde documentatie biedt niet de mogelijkheid om via GitHub feedback te bewerken of te geven. Gebruik https://aka.ms/provide-feedback het formulier om feedback te geven over gelokaliseerde inhoud.

Licentieovereenkomst voor bijdragers

U moet de .NET Foundation Contribution License Agreement (CLA) ondertekenen voordat uw pull-aanvraag wordt samengevoegd. Dit is een eenmalige vereiste voor projecten in de .NET Foundation. Ga voor meer informatie over Contribution License Agreements (CLA's) naar Wikipedia.

De overeenkomst: .NET Foundation Contributor License Agreement (CLA)

U hoeft de overeenkomst niet van tevoren te ondertekenen. U kunt uw pull-aanvraag klonen, vertakken en verzenden zoals u gewend bent. Wanneer uw pull-aanvraag wordt gemaakt, wordt deze door een CLA-bot geclassificeerd. Als het een kleine wijziging betreft (u corrigeert bijvoorbeeld een typfout), dan krijgt de pull-aanvraag het label cla-not-required. Anders wordt de aanvraag als cla-required geclassificeerd. Zodra u de CLA hebt ondertekend, krijgen de huidige en alle toekomstige pull-aanvragen het label cla-signed.