Dela via

Bidra till kvalitetsförbättringar

För Hacktoberfest 2022har vi testat en process för att bidra med kvalitetsförbättringar i PowerShell-innehållet. Den här guiden generaliserar den processen för att definiera ett sätt med låg friktion för communitymedlemmar att förbättra kvaliteten på dokumentationen.

Vi fokuserar på dessa kvalitetsområden:

Projektspårning

Vi övervakar bidrag med PowerShell Docs Kvalitetsbidrag GitHub-projektet.

Projektsidan har flera vyer för de problem och pr:ar som är relaterade till den här insatsen:

Formatering av kodexempel

Alla kodexempel bör följa riktlinjerna för formatmall för PowerShell-innehåll. Dessa regler upprepas i förkortad form här för enkelhetens skull:

  • Alla kodblock ska finnas inom tre bakåtvända citationstecken (```).
  • Radlängden för kodblock är begränsad till 90 tecken för cmdlet-referensartiklar.
  • Radlängden för kodblock är begränsad till 76 tecken för about_* artiklar.
  • Undvik att använda radfortsättningstecken (`) i PowerShell-kodexempel.
    • Använd splatting eller naturliga radbrytningsmöjligheter, till exempel efter pipe (|) tecken, öppna klammerparenteser (}), parenteser (() och hakparenteser ([) för att begränsa linjelängden.
  • Inkludera endast PowerShell-prompten för illustrativa exempel där koden inte är avsedd för kopieringsdeplikering.
  • Använd inte alias i exempel om du inte specifikt dokumenterar aliaset.
  • Undvik att använda positionsparametrar. Använd parameternamnet, även om parametern är positionell.

Syntax för formateringskommando

Alla prosa bör följa riktlinjerna för stil för PowerShell-innehåll. Dessa regler upprepas här för enkelhetens skull:

  • Använd alltid det fullständiga namnet för cmdletar och parametrar. Undvik att använda alias om du inte specifikt demonstrerar aliaset.
  • Egenskap, parameter, objekt, typnamn, klassnamn, klassmetoder ska vara fetstil.
    • Egenskaps- och parametervärden ska omslutas i backticks (`).
    • När du refererar till typer med det hakparenteserade formatet använder du backticks. Till exempel: [System.Io.FileInfo]
  • PowerShell-modulnamn bör vara fetstil.
  • PowerShell-nyckelord och operatorer ska vara gemener.
  • Använd rätt (Pascal)-hölje för cmdlet-namn och parametrar.
  • När du refererar till en parameter efter namn ska namnet vara fetstil.
  • Använd parameternamnet med bindestrecket om du illustrerar syntaxen. Omslut parametern i backticks.
  • När du visar exempel på användning av ett externt kommando ska exemplet omslutas i backticks. Inkludera alltid filnamnstillägget för det externa kommandot.

För att markdown-källan ska kunna underhållas och läsas i vår dokumentation konverterar vi vår konceptuella dokumentation till att använda länkreferenser i stället för infogade länkar.

Till exempel, i stället för:

The [Packages tab][31] displays all available
packages in the PowerShell Gallery.

Det bör vara:

The [Packages tab][31] displays all available packages in the PowerShell Gallery.

Anmärkning

När du ersätter en infogad länk flödar du om innehållet så att det omsluts med 100 tecken. Du kan använda reflow-markdown VS Code-tillägget för att snabbt omformatera stycket.

Längst ned i filen lägger du till en markdown-kommentar före definitionen av länkarna.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Se till att:

  1. Länkarna definieras i den ordning de visas i dokumentet.
  2. Varje länk pekar på rätt plats.
  3. Länkreferensdefinitionerna finns längst ned i filen efter markdown-kommentaren och är i rätt ordning.

Markdown-lintning

Om du öppnar artikeln i VS Code visas lintningsvarningar för alla artiklar i någon av de deltagande lagringsplatserna. Åtgärda någon av de här varningarna du hittar, förutom:

Kontrollera linjelängderna och använd Reflow Markdown-tillägget för att åtgärda eventuella långa linjer.

Stavning

Trots vårt bästa arbete kommer stavfel och felstavningar igenom och hamnar i dokumentationen. Dessa misstag gör dokumentationen svårare att följa och lokalisera. Att åtgärda dessa misstag gör dokumentationen mer läsbar, särskilt för icke-engelsktalande som förlitar sig på korrekta översättningar.

Processen

Vi rekommenderar att du väljer en eller flera av kvalitetsområdena och en artikel (eller en grupp med artiklar) för att förbättra. Använd följande steg för att vägleda ditt arbete:

  1. Kontrollera i projektet för problem som rapporterats inom det här projektet för att undvika dubbelarbete.

  2. Öppna ett nytt problem på rätt lagringsplats:

  3. Följ vår deltagarguide för att komma igång med att göra dina ändringar.

  4. Skicka din pull request. Se till:

    1. PR-titeln har prefixet Quality:.

    2. PR-brödtexten refererar till det problem det löser som ett oordnat listobjekt och använder ett av -länkenyckelorden.

      Om du till exempel arbetar med problem 123bör brödtexten i din pr innehålla följande Markdown:

      - resolves #123

    När du har skickat PR-begäran granskar underhållarna ditt arbete och arbetar med dig för att slå ihop den.

  • Last updated on