.NET-dokumentaatiosäilöjen kehittämiseen osallistuminen

Kiitos mielenkiinnostasi .NET-dokumentaation kehittämiseen!

Tässä asiakirjassa kerrotaan, miten voit osallistua .NET-dokumentaatiosivustolla olevien artikkelien ja koodiesimerkkien kehittämiseen. Osallistuminen voi olla esimerkiksi kirjoitusvirheiden korjausta tai uusien artikkelien kirjoittamista.

.NET-dokumentaatiosivusto on muodostettu useista säilöistä. Nämä ovat vain joitakin niistä:

• .NET-käsiteartikkelit ja -koodikatkelmat
• Koodiesimerkit ja -katkelmat
• .NET-ohjelmointirajapinnan viittaus
• .NET Compiler Platform SDK -viite
• ML.NET-ohjelmointirajapintaviite

Osallistumisohjeet

Arvostamme yhteisön panosta dokumentaatioon. Seuraava luettelo sisältää joitakin sääntöjä, jotka on syytä pitää mielessä julkatessasi tietoja .NET-asiakirjoihin:

• ÄLÄ yllätä meitä suurilla pull-pyynnöillä. Luo sen sijaan aihe ja aloita keskustelu, niin voimme sopia jatkotoimista ennen kuin käytät asiaan paljon aikaa.
• ÄLÄ sisällytä mallikoodia artikkeliin.
• KÄYTÄ koodilla olevaa katkelman projektia, joka upotetaan artikkeliin.
• NOUDATA näitä ohjeita ja sävyä koskeviin ohjeisiin.
• KÄYTÄmallitiedostoa työsi pohjana.
• LUO erillinen haara haaraumaasi ennen artikkelien muokkaamista.
• NOUDATAGitHub-työnkulkua.
• JULKAISE blogikirjoituksia ja twiittejä (tai mitä tahansa) sisältöjulkaisuistasi, jos haluat.

Näitä ohjeita noudattamalla voit varmistaa paremman käyttökokemuksen itsellesi ja meille.

Osallistumisprosessi

Vaihe 1: Jos olet kiinnostunut kirjoittamaan uutta sisältöä tai muokkaamaan sisältöä perusteellisesti, avaa uusi aihe, jossa kuvaat, mitä haluat tehdä. Asiakirjakansion sisältö on järjestetty osioihin, jotka näkyvät sisällysluettelossa . Määritä, missä kohtaa haluat aiheen näkyvän sisällysluettelossa. Pyydä palautetta ehdotuksestasi.

-tai-

Valitse olemassa oleva ongelma ja korjaa se. Voit tutustua avoimien ongelmien luetteloon ja osallistua niiden aiheiden käsittelyyn, joista olet kiinnostunut:

• Voit suodattaa hyvän ensimmäisen ongelman selitteen perusteella sopivat ensimmäiset ongelmat.
• Voit suodattaa ohjetunnisteen perusteella yhteisön osallistumiseen sopivat ongelmat. Nämä ongelmat edellyttävät yleensä vähimmäiskontekstia.
• Kokeneet osallistujat voivat käsitellä kaikkia kiinnostavia aiheita.

Jos löytyy aihe, jota haluat käsitellä, lisää kommentti ja kysy siinä, onko aihe avoin.

Kun olet valinnut tehtävän käsiteltäväksi, luo GitHub-tili ja siirry vaiheeseen 2.

Vaihe 2: Tee säilöstä /dotnet/docs (tai mihin säilöön osallistut) tarpeen mukaan ja luo haara tekemiäsi muutoksia varten.

Jos haluat tehdä pieniä muutoksia, katso Muokkaa selaimessa.

Vaihe 3: Tee muutokset tähän uuteen haaraan.

Jos aihe on uusi, voit käyttää tätä mallitiedostoa pohjana. Se sisältää kirjoitusohjeita, ja siinä kerrotaan myös kunkin artikkelin vaatimat metatiedot, kuten tekijätiedot. Lisätietoja Microsoft Learn -sisällössä käytettävästä Markdown-syntaksista on artikkelissa Markdown-viiteopas.

Siirry kansioon, joka vastaa artikkelisi sisällysluettelolle määritettyä sijaintia vaiheessa 1. Kansio sisältää kyseisen osion kaikkien artikkelien Markdown-tiedostot. Luo tarvittaessa uusi kansio tiedostojasi varten. Osion pääartikkeli on index.md.

Luo kuville ja muille staattisille resursseille alikansio media siihen kansioon, joka sisältää artikkelisi, ellei alikansio ole jo olemassa. Luo media-kansioon alikansio, jonka nimi on artikkelin nimen mukainen (paitsi index-tiedostolle). Lisätietoja tiedostojen tallennussijainnista on Esimerkkikansiorakenne-osassa.

Älä sisällytä artikkeliin sisäistä koodia, ellet esittele rakennetta, jota ei ole käännettävä. Käytä sen sijaan koodikatkelmien projektia ja sisällytä koodi koodilaajennuksen avulla. Se varmistaa, että CI-järjestelmämme vahvistaa mallikoodisi.

Luo koodikatkelmia varten alikansio katkelmat siihen kansioon, joka sisältää artikkelisi, ellei alikansio ole jo olemassa. Luo katkelmien kansioon alikansio, jolla on artikkelin nimi. Useimmissa tapauksissa sinulla on koodikatkelmia kaikille .NET-pääkielille (C#, F# ja Visual Basic). Luo siinä tapauksessa alikansiot csharp, fsharp ja vb kolmea projektia varten. Jos luot katkelman artikkelista kansiossa docs/csharp, docs/fsharp tai docs/visual-basic, katkelma on vain yhdellä kielellä, joten voit jättää kielialikansion pois. Lisätietoja tiedostojen tallennussijainnista on Esimerkkikansiorakenne-osassa.

Koodikatkelmat ovat lyhyitä ja kohdistettuja esimerkkikoodeja, jotka havainnollistavat artikkelin käsitteitä. Suuremmat ohjelmat, jotka on tarkoitettu ladattaviksi ja tutkittaviksi, on sijoitettava dotnet/Samples-säilöön. Täydellisiä näytteitä käsitellään osiossa, joka koskee näytteiden luomiseen osallistumista.

Vaihe 4: Tee haarastasi pull-pyyntö oletushaaraan.

Tärkeä

Automaattisen kommentoinnin toiminnot eivät ole tällä hetkellä käytettävissä .NET-asiakirjasäilöissä. .NET-asiakirjatiimi tarkistaa ja yhdistää pull-pyyntösi.

Kunkin pull-pyynnön tulisi yleensä koskea vain yhtä ongelmaa, ellei samaan PULL-ongelmaan liity useita ongelmia. Pull-pyynnöllä voidaan muokata yhtä tai useaa tiedostoa. Jos olet tekemässä useita korjauksia eri tiedostoihin, on suositeltavaa tehdä erilliset pull-pyynnöt.

Jos pull-pyyntösi korjaa olemassa olevan ongelman, lisää avainsana PULL-pyynnön Fixes #Issue_Number kuvaukseen. Tällä tavalla ongelma suljetaan automaattisesti, kun pull-pyyntö yhdistetään. Lisätietoja on kohdassa Pull-pyynnön linkittäminen ongelmaan avainsanan avulla.

.NET-tiimi tarkistaa pull-pyyntösi ja ilmoittaa sinulle, onko muita päivityksiä/muutoksia, jotka on tehtävä, jotta pyyntösi voidaan hyväksyä.

Vaihe 5: Tee tarvittavat muutokset tiimin kanssa käymiesi keskustelujen mukaisesti.

Ylläpitäjät yhdistävät pull-pyyntösi oletushaaraan, kun palaute on otettu käyttöön ja muutoksesi on hyväksytty.

Lähetämme kaikki vahvistukset oletushaarasta live-haaraan, jonka jälkeen voit nähdä panoksesi reaaliaikaisesti .NET-dokumentaatiossa. Teemme julkaisut tavallisesti päivittäin arkipäivinä.

Esimerkkikansiorakenne

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

Muistiinpano

Katkelmien alla olevia kielikansioita ei tarvita kielioppaan alueella, jossa on oletetusti vain yksi kieli. Esimerkiksi C#-oppaassa oletetaan, että kaikki katkelmat ovat C#-koodikatkelmia.

Yllä näkyvä rakenne sisältää yhden kuvan portability_report.png ja kolme koodiprojektia, jotka sisältävät koodikatkelmia, joita käsitellään porting-overview.md-artikkelissa.

Katkelmia /jaettua kansiota käytetään katkelmissa, jotka saattavat kattaa useita artikkeleita samassa pääkansiossa, kuten edellisen esimerkin portikansiossa . Käytä jaettua kansiota vain, jos sinulla on siihen tietty syy, kuten XAML-koodi, johon viitataan useissa artikkeleissa, mutta jota ei voi kääntää artikkelikohtaisessa kansiossa.

Mediasisältöä voidaan jakaa artikkeleiden kesken myös silloin, kun nämä artikkelit ovat samassa pääkansiossa, kuten edellisen esimerkin porttikansiossa . Tätä jaettua kansiota tulee välttää, jos mahdollista, ja sitä käytetään vain, kun se on järkevää. Voi olla esimerkiksi järkevää jakaa esiteltyä sovellusta varten yhteinen latausnäyttö tai jakaa Visual Studio -dialogeja, joita käytetään uudelleen useissa artikkeleissa.

Tärkeä

Historiallisista syistä monet sisällytetyt katkelmat on tallennettu /samples-kansioon dotnet/docs-säilöön. Jos teet artikkeliin suuria muutoksia, nämä katkelmat pitää siirtää uuteen rakenteeseen. Älä kuitenkaan välitä katkelmien siirtämisestä pienten muutosten vuoksi.

Näytteisiin osallistuminen

Erittelemme sisältöämme tukevat koodit seuraavasti:

• Näytteet: lukijat voivat ladata ja suorittaa näytteitä. Kaikkien näytteiden pitäisi olla valmiita sovelluksia tai kirjastoja. Jos näyte muodostaa kirjaston, sen pitää sisältää vähintään yksikkötestit tai sovellus, joka antaa lukijoiden suorittaa koodin. Niissä käytetään usein montaa teknologiaa, ominaisuutta tai työkalupakettia. Kunkin näytteen readme.md-tiedosto viittaa artikkeliin, jotta voit lukea lisää kussakin näytteessä käsitellyistä käsitteistä.
• Katkelmat: edustavat suppeampaa käsitettä tai tehtävää. Ne voidaan kääntää, mutta niitä ei ole tarkoitettu kokonaisiksi sovelluksiksi. Niiden suorittamisen pitäisi onnistua, mutta ne eivät ole tyypillisen skenaarion esimerkkisovelluksia. Niistä pyritään sen sijaan tekemään niin pieniä kuin mahdollista yksittäisen käsitteen tai ominaisuuden esittämiseksi. Niiden pitäisi olla koodinsa laajuudelta enintään yhden näytön kokoisia.

Näytteet tallennetaan dotnet/samples-säilöön. Olemme kehittämässä mallia, jossa näytekansion rakenne vastaa asiakirjakansion rakennetta. Noudatamme seuraavia standardeja:

• Ylimmän tason kansioiden nimet vastaavat dokumentit-säilön ylimmän tason kansioiden nimiä. Esimerkki: asiakirjat-säilössä on koneoppiminen/opetusohjelmat-kansiot, ja koneoppimisen opetusohjelmien näytteet ovat näytteet/koneoppiminen/opetusohjelmat-kansiossa.

Lisäksi kaikkien ydin- ja vakio-kansioissa olevien näytteiden pitäisi kääntyä ja toimia kaikissa .NET Coren tukemissa alustoissa. CI-koontijärjestelmämme tekee tämän pakotetusti. Ylimmän tason sovelluskehys-kansio sisältää näytteitä, jotka on käännetty ja vahvistettu vain Windowsille.

Näyteprojektien pitäisi kääntyä ja toimia mahdollisimman laajassa joukossa ympäristöjä, joita näyte tukee. Tämä tarkoittaa käytännössä .NET Core -pohjaisten konsolisovellusten kääntämistä aina kun mahdollista. Tietylle verkko- tai käyttöliittymäsovelluskehykselle tarkoitettujen näytteiden tulee lisätä nämä työkalut tarpeen mukaan. Näitä ovat esimerkiksi verkkosovellukset, mobiilisovellukset tai WPF- tai WinForms-sovellukset.

Tavoitteenamme on kehittää CI-järjestelmä kaikelle koodille. Kun teet päivityksiä näytteisiin, varmista, että kukin päivitys on osa käännettävää projektia. Ihanteellista olisi, jos lisäisit näytteisiin myös oikeellisuustestit.

Kunkin luomasi kokonaisen näytteen tulee sisältää readme.md-tiedosto. Tämän tiedoston tulee sisältää lyhyt näytteen kuvaus (yksi tai kaksi kappaletta). readme.md-tiedostosi tulee kertoa lukijoille, mitä he oppivat näytteeseen tutustumisesta. readme.md-tiedoston tulee sisältää myös linkki .NET-dokumentaatiosivustolla olevaan live-asiakirjaan. Jos haluat määrittää, että tietty kyseisessä säilössä oleva tiedosto yhdistetään kyseiseen sivustoon, korvaa säilön polun /docs osoitteella https://learn.microsoft.com/dotnet.

Aiheesi tulee myös sisältämään linkit siihen näytteeseen. Tee suora linkitys näytteen GitHub-kansioon.

Uuden näytteen kirjoittaminen

Näytteet ovat kokonaisia ohjelmia ja kirjastoja, jotka on tarkoitettu ladattaviksi. Ne voivat olla pieniä, mutta ne havainnollistavat käsitteitä tavalla, jonka avulla käyttäjät voivat tutkia ja kokeilla niitä itse. Näytteiden ohjeet varmistavat, että lukijat voivat ladata ja tutkia niitä. Tutki Parallel LINQ (PLINQ)- -näytteitä esimerkkinä ohjeista.

1. Näytteesi on oltava osa käännettävää projektia. Jos mahdollista, projektien pitäisi olla käännettävissä kaikissa .NET Coren tukemissa ympäristöissä. Poikkeuksia ovat näytteet, jotka esittelevät ympäristökohtaisen ominaisuuden tai ympäristökohtaisen työkalun.

2. Näytteesi tulee yhdenmukaisuuden säilyttämiseksi noudattaa suorituksenaikaista koodaustyyliä .

   Suosimme lisäksi static-menetelmiä esiintymämenetelmien sijaan, kun esitellään jotain, joka ei vaadi uuden objektin esiintymän luomista.

3. Näytteesi tulee sisältää asianmukainen poikkeusten käsittely. Sen tulee käsitellä kaikki poikkeukset, jotka todennäköisesti ilmenevät näytteen kontekstissa. Esimerkiksi näytteen, joka kutsuu Console.ReadLine-menetelmää käyttäjän syötteen vastaanottamiseen, tulee käyttää asianmukaista poikkeustenkäsittelyä, kun syötemerkkijono välitetään argumenttina menetelmälle. Samoin jos näytteesi odottaa menetelmäkutsun epäonnistuvan, siitä seuraava poikkeus tulee käsitellä. Käsittele aina menetelmässä ilmenevät menetelmän omat poikkeukset perusluokkapoikkeusten kuten Exception- SystemException-poikkeusten sijaan.

Näytteen luominen:

1. Julkaise aihe tai lisää kommentti olemassa olevaan aiheeseen, jota olet muokkaamassa.

2. Kirjoita aihe, jossa kuvaillaan näytteessäsi esitellyt konseptit (esimerkki: docs/standard/linq/where-clause.md).

3. Kirjoita näytteesi (esimerkki: WhereClause-Sample1.cs).

4. Luo Program.cs, joka sisältää näytteitäsi kutsuvan Main-aloituskohdan. Jos se on jo olemassa, lisää kutsu näytteeseesi:

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

Voit luoda minkä tahansa .NET-katkelman tai näytteen .NET CLI:n avulla, joka voidaan asentaa .NET SDK:n kanssa. Käännä ja suorita näytteesi:

1. Mene näytekansioon ja käännä näyte virheiden tarkistamiseksi:

   dotnet build
   

2. Suorita näytteesi:

   dotnet run
   

3. Lisää readme.md näytteesi päähakemistoon.

   Sen tulee sisältää lyhyt koodin kuvaus sekä viite artikkeliin, joka viittaa näytteeseen. readme.md-tiedoston yläosassa on oltava metatiedot, joita näyteselain käyttää. Otsikkolohkossa on oltava seuraavat kentät:

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

   • languages-kokoelman tulee sisältää vain kielet, jotka ovat saatavilla näytteellesi.
   • products-kokoelman tulee sisältää vain tuotteet, jotka ovat olennaisia näytteellesi.

Ellei muuta ole mainittu, kaikki näytteet voidaan muodostaa komentoriviltä missä tahansa .NET:n tukemassa ympäristössä. Jotkin näytteet ovat Visual Studiota varten ja vaativat Visual Studio 2017:n tai uudemman. Lisäksi jotkin näytteet esittelevät ympäristökohtaisia ominaisuuksia ja vaativat tietyn ympäristön. Muut näytteet ja katkelmat vaativat .NET Frameworkin ja toimivat Windows-ympäristöissä, ja niitä varten tarvitaan sen Framework-version Developer Packin, jolle näyte tai katkelma tehdään.

Vuorovaikutteinen C#-käyttö

Kaikki artikkeliin sisällytetyt katkelmat ilmaisevat lähdekielen kielitunnisteella . C#:n lyhyet koodikatkelmat voivat käyttää csharp-interactive kielitunnistetta määrittämään C#-katkelman, joka suoritetaan selaimessa. (Tekstiin sidotut koodikatkelmat käyttävät -csharp-interactivetunnistetta. Käytä lähteestä sisällytettyjä katkelmia varten -tunnistettacode-csharp-interactive.) Nämä koodikatkelmat näyttävät koodi-ikkunan ja tietoikkunan artikkelissa. Tulosikkunassa näkyvät vuorovaikutteisen koodin suorittamisen mahdolliset tulokset, kun käyttäjä on suorittanut katkelman.

Vuorovaikutteinen C#-käyttö muuttaa katkelmien käsittelemistapaa. Vierailijat voivat suorittaa katkelman nähdäkseen tulokset. Eri tekijöistä voidaan päätellä, pitäisikö katkelman tai sitä vastaavan tekstin sisältää tietoja tuloksista.

Milloin odotetut tulokset kannattaa näyttää ilman katkelman suorittamista?

• Aloittelijoille tarkoitettujen näytteiden tulee näyttää tulokset, jotta lukijat voivat verrata omien töidensä tuloksiin, sekä odotettu vastaus.
• Katkelmien, joissa tulos on keskeinen osa aihetta, tulee näyttää tämä tuloste. Esimerkiksi muotoiltua tekstiä olevien artikkeleiden tulee näyttää tekstimuoto ilman katkelman suorittamista.
• Kun sekä katkelman että odotettu tulos on lyhyt, harkitse tuloksen näyttämistä. Se säästää jonkin verran aikaa.
• Artikkeleissa, joissa kerrotaan, miten nykyinen maa-asetus tai muuttumaton maa-asetus vaikuttaa tulokseen, tulee selittää odotettu tulos. Vuorovaikutteinen REPL (Read Evaluate Print Loop) suoritetaan Linux-pohjaisessa isännässä. Oletusmaa-asetus ja muuttumaton maa-asetus tuottavat eri tulokset eri käyttöjärjestelmissä ja koneissa. Artikkelissa tulee selittää, millaiset tulokset ovat Windows-, Linux- ja Mac-järjestelmissä.

Milloin odotettu tulos kannattaa jättää pois katkelmasta?

• Artikkeleissa, joissa katkelman tuloksena on suurempi tulos, tuloksia ei kannata lisätä kommentteihin. Koodi jää piiloon, kun katkelman suorittaminen on tehty.
• Artikkelit, joissa katkelmä esittelee aiheen, mutta joissa tulokset eivät ole olennaiset aiheen ymmärtämiseen. Tällainen voi olla esimerkiksi koodi, joka suorittaa LINQ-kyselyn kyselysyntaksin esittämiseksi ja näyttää sitten tuloskokoelman jokaisen kohteen.

Muistiinpano

Saatat huomata, että jotkin aiheet eivät tällä hetkellä ole täällä määritettyjen ohjeiden mukaiset. Kehitämme sivustoa jatkuvasti, jotta saamme siitä mahdollisimman yhdenmukaisen. Tutustu avoimiin aiheisiin, joita tällä hetkellä seuraamme yhdenmukaisuuden parantamiseksi.

Sisällön antaminen muille kuin englanninkielisille sisällöille

Konekäännettyihin sisältöihin vaikuttamista ei tällä hetkellä hyväksytä. Olemme siirtyneet neuroverkkoihin perustuvaan konekääntimeen konekäännettyjen sisältöjen parantamiseksi. Hyväksymme ja kannustamme vaikuttamista ihmiskääntäjien kääntämiin sisältöihin, joita käytetään neuroverkkoihin perustuvan konekääntimen opettamiseen. Siksi vaikuttaminen ihmiskäännettyihin sisältöihin parantaa ajan myötä sekä ihmis- että konekäännettyjä sisältöjä. Konekäännetyissä aiheissa on vastuuvapausilmoitus, joka kertoo, että osa aiheesta voi olla konekäännettyä, eikä Muokkaa-painike ole näkyvissä, koska muokkaus ei ole käytössä.

Muistiinpano

Useimmat lokalisoidut ohjeet eivät tarjoa mahdollisuutta muokata tai antaa palautetta GitHubin kautta. Jos haluat antaa palautetta lokalisoidusta sisällöstä, käytä https://aka.ms/provide-feedback lomaketta.

Osallistujan käyttöoikeussopimus

Sinun tulee allekirjoittaa .NET Foundation -osallistujien lisenssisopimus ennen pull-pyyntösi yhdistämistä. Tämä vaaditaan kerran .NET Foundation-projekteja varten. Lisätietoja osallistujien lisenssisopimuksesta on Wikipediassa.

Sopimus: .NET Foundation -osallistujan käyttöoikeussopimus (CLA)

Sinun ei tarvitse allekirjoittaa sopimusta etukäteen. Voit kloonata, suorittaa fork-toimintoja ja lähettää pull-pyyntösi tavalliseen tapaan. Kun pull-pyyntösi on luotu, CLA-botti luokittelee sen. Jos muutos on pieni (esimerkiksi korjasit kirjoitusvirheen), pull-pyynnölle asetetaan tunniste cla-not-required. Muutoin sille asetetaan luokitus cla-required. Kun olet allekirjoittanut osallistujan lisenssisopimuksen, nykyinen ja tulevat pull-pyyntösi saavat tunnisteen cla-signed.