Wprowadzenie do dokumentacji programu PowerShellGet started contributing to PowerShell documentation

Ten artykuł zawiera omówienie sposobu rozpoczynania pracy jako współautor w dokumentacji programu PowerShell.This article is an overview of how to get started as a contributor to the PowerShell documentation.

PowerShell — struktura dokumentówPowerShell-Docs structure

Repozytorium PowerShell-docs jest podzielone na dwie grupy zawartości.The PowerShell-Docs repository is divided into two groups of content. Gałęzie git służą do zarządzania tym, jak i kiedy dokumentacja jest publikowana.Git branches are used to manage how and when documentation gets published.

Zawartość referencyjnaReference content

Zawartość referencyjna to dokumentacja poleceń cmdlet programu PowerShell dla poleceń cmdlet, które są dostarczane w programie PowerShell.The reference content is the PowerShell cmdlet reference for the cmdlets that ship in PowerShell. Odwołanie jest zbierane w folderach wersji (5,1, 6, 7,0 i 7,1).The reference is collected in versions folders (5.1, 6, 7.0, and 7.1). Ta zawartość zawiera informacje dotyczące poleceń cmdlet tylko dla modułów dostarczanych z programem PowerShell.This content contains cmdlet reference only for the modules that ship with PowerShell. Ta zawartość jest również używana do tworzenia informacji pomocy wyświetlanych przez Get-Help polecenie cmdlet.This content is also used to create the help information displayed by the Get-Help cmdlet.

Uwaga

Spis treści (TOC) dla zawartości referencyjnej jest automatycznie generowany przez system publikacji.The Table of Contents (TOC) for reference content is autogenerated by the publishing system. Nie musisz aktualizować spisu treści.You don't have to update the TOC.

Zawartość koncepcyjnaConceptual content

Dokumentacja dotycząca pojęć zawiera następującą zawartość:The conceptual documentation includes the following content:

  • Informacje o wersjiRelease notes
  • Instrukcje dotyczące instalacjiSetup instructions
  • Przykładowe skrypty i artykuły z poradamiSample scripts and how-to articles
  • Dokumentacja DSCDSC documentation
  • Dokumentacja zestawu SDKSDK documentation

Dokumentacja koncepcyjna nie jest zorganizowana według wersji.The conceptual documentation is not organized by version. Wszystkie artykuły są wyświetlane dla każdej wersji programu PowerShell.All articles are displayed for every version of PowerShell. Pracujemy nad utworzeniem artykułów specyficznych dla wersji.We are working to create version-specific articles. Gdy ta funkcja jest dostępna w naszej dokumentacji, ten przewodnik zostanie zaktualizowany o odpowiednie informacje.When that feature is available in our documentation, this guide will be update with the appropriate information.

Uwaga

W przypadku dodania lub usunięcia artykułu koncepcyjnego należy zaktualizować spis treści i uwzględnić go w żądaniu ściągnięcia.Anytime a conceptual article is added, removed, or renamed, the TOC must be updated and included in the pull request.

Korzystanie z gałęzi gitUsing git branches

Gałąź domyślna dla programu PowerShell — dokumentacja jest staging gałęzią.The default branch for PowerShell-Docs is the staging branch. Zmiany wprowadzone w gałęziach roboczych są scalane z staging gałęzią przed opublikowaniem.Changes made in working branches are merged into the staging branch before then being published. Na raz w tygodniu staging gałąź jest scalana z live gałęzią.About once a week, the staging branch is merged into the live branch. liveGałąź zawiera zawartość opublikowaną w usłudze docs.Microsoft.com.The live branch contains the content that is published to docs.microsoft.com. Zmiany nigdy nie powinny być wprowadzane bezpośrednio w live gałęzi.Changes should never be made directly in the live branch.

Jeśli przesyłasz zmianę dokumentacji, która dotyczy tylko niewydanej wersji programu PowerShell, sprawdź, czy istnieje gałąź wydania dla tej wersji.If you are submitting a change to documentation that only applies to an unreleased version of PowerShell, check to see if there is a release branch for that version. Wszystkie zmiany, które mają zastosowanie do konkretnej przyszłej wersji, powinny być skierowane do gałęzi wydania.All changes that apply to a specific, future version should be targeted at the release branch. Gałęzie wydań mają następujący wzorzec nazwy: release-<version>.Release branches have the following name pattern: release-<version>.

Przed rozpoczęciem wprowadzania jakichkolwiek zmian Utwórz gałąź roboczą w lokalnej kopii repozytorium programu PowerShell-docs.Before starting any changes, create a working branch in your local copy of the PowerShell-Docs repository. Powinien to być klon rozwidlenia.This should be a clone of your fork. Upewnij się, że lokalne repozytorium zostało zsynchronizowane przed utworzeniem gałęzi roboczej.Be sure to synchronize your local repository before creating your working branch. Gałąź robocza powinna zostać utworzona na podstawie aktualizacji do tej kopii staging release gałęzi lub.The working branch should be created from an update-to-date copy of the staging or release branch.

Wprowadź zmiany, które chcesz przesłać po zakończeniu procesu, w sekcji wprowadzenie do zmiany w przewodniku centralnym współautor.Make the changes you want to submit following the process in the Making your change section of the central Contributor's Guide.

Tworzenie nowych artykułówCreating new articles

Dla każdego nowego dokumentu, który ma być współtworzony, należy utworzyć problem w usłudze GitHub.A GitHub issue must be created for any new document you want to contribute. Sprawdź istniejące problemy, aby upewnić się, że nie są duplikowane wysiłki.Check for existing issues to make sure you're not duplicating efforts. Problemy przypisane do kogoś są uważane za "w toku".Issues that are assigned to someone are considered to be "in progress". Jeśli chcesz współpracować nad problemem, skontaktuj się z osobą przypisaną do tego problemu.If you wish to collaborate on an issue, contact the person assigned to the issue.

Podobnie jak w przypadku procesuprogramu PowerShell RFC, tworzenie problemu przed zapisaniem zawartości gwarantuje, że nie poświęcasz dużo czasu i wysiłku na coś, co jest odrzucane przez zespół programu PowerShell.Similar to the PowerShell RFC process, creating an issue before writing the content ensures that you don't spend a lot of time and effort on something that gets rejected by the PowerShell-Docs team. Umożliwia to również nam konsultacje z Twoim zakresem zawartości oraz miejsce, w którym powinny być zgodne z dokumentacją programu PowerShell.This also allows us to consult with you on the scope of the content and where it should fit within the PowerShell documentation.

Aktualizowanie istniejących artykułówUpdating existing articles

Jeśli ma to zastosowanie, artykuł referencyjny poleceń cmdlet jest duplikowany we wszystkich wersjach programu PowerShell.Where applicable, cmdlet reference article are duplicated across all versions of PowerShell. W przypadku zgłaszania problemu dotyczącego dokumentacji poleceń cmdlet lub About_ artykułu należy określić, które wersje mają wpływ na problem.When reporting an issue about a cmdlet reference or an About_ article, you must specify which versions are affected by the issue. Szablon problemu w usłudze GitHub zawiera listę kontrolną wersji.The issue template in GitHub includes a checklist of versions. Użyj pól wyboru, aby określić, które wersje zawartości podlegają usterce.Use the checkboxes to specify which versions of the content are affected. Po przesłaniu zmiany do artykułu dotyczącego problemu mającego wpływ na wiele wersji zawartości należy zastosować odpowiednią zmianę do każdej wersji pliku.When you submit a change to a article for an issue that affects multiple versions of the content, you must apply the appropriate change to each version of the file.

Następne krokiNext steps

Zobacz przesyłanie żądania ściągnięciaSee Submitting a pull request