Začínáme přispívat do dokumentace k PowerShellu

Tento článek je přehledem toho, jak začít jako přispěvatel do dokumentace k PowerShellu.

struktura PowerShell-Docs

V úložišti PowerShell-Docs existují tři kategorie obsahu:

  • referenční obsah
  • koncepční obsah
  • metadata a konfigurační soubory

Referenční obsah

Referenční obsah je návod ke cmdletům PowerShellu, které jsou součástí PowerShellu. Cmdlet reference se shromažďuje ve složkách s verzemi (například 5.1, 7.4, 7.5 a 7.6), které obsahují reference na moduly, které jsou dodávány s PowerShellem. Tento obsah slouží také k vytvoření informací nápovědy zobrazených příkazem Get-Help.

Koncepční obsah

Koncepční dokumentace není uspořádaná podle verze. Všechny články se zobrazují pro každou verzi PowerShellu.

Poznámka

Kdykoli se přidá, odebere nebo přejmenuje koncepční článek, musí se aktualizovat obsah dokumentu. Všechny odstraněné nebo přejmenované soubory musí být přesměrovány.

Soubory metadat

Tento projekt obsahuje několik typů souborů metadat. Soubory metadat řídí chování našich nástrojů sestavení a systému publikování. Tyto soubory mohou měnit pouze PowerShell-Docs správci a schválení přispěvatelé. Pokud se domníváte, že by se měl změnit metasoubor, otevřete problém a proberte potřebné změny.

Meta soubory v kořenovém adresáři úložiště

  • .* – konfigurační soubory v kořenovém adresáři úložiště
  • *.md – dokumentace projektu v kořenovém adresáři úložiště
  • *.yml – dokumentace projektu v kořenovém adresáři úložiště
  • .devcontainer/* – konfigurační soubory devcontainer
  • .github/**/* – šablony, akce a další meta soubory GitHubu
  • .vscode/**/* – konfigurace rozšíření VS Code
  • assets/* – obsahuje soubory ke stažení, které jsou uvedené v dokumentaci.
  • redir/* – obsahuje soubory mapování přesměrování
  • tests/* – testovací nástroje používané systémem sestavení
  • tools/* – další nástroje používané systémem sestavení

Meta soubory v sadě dokumentace

  • reference/**/*.json – konfigurační soubory pro docset
  • reference/**/*.yml – TOC a další soubory strukturovaného obsahu
  • reference/bread/* – konfigurace navigace s drobečkovou stopou
  • reference/includes/* – zahrnutí souborů markdownu
  • reference/mapping/* – konfigurace mapování verzí
  • reference/**/media/** – soubory obrázků používané v dokumentaci
  • reference/module/* – konfigurace stránky Modulového prohlížeče

Vytváření nových článků

Pro každý nový dokument, ke kterému chcete přispět, je potřeba vytvořit issue na GitHubu. Zkontrolujte stávající problémy, abyste se ujistili, že neuplikujete úsilí. Problémy, které jsou přiřazené, jsou považovány za in progress. Pokud chcete na problému spolupracovat, obraťte se na osobu přiřazenou k problému.

Podobně jako v procesu RFC pro PowerShell (a ), vytvořte úkol před napsáním obsahu. Problém zajišťuje, že nebudete ztrácet čas a úsilí na práci, která bude odmítnuta týmem PowerShell-Docs. Tento problém nám umožňuje poradit se s vámi o rozsahu obsahu a o tom, kde se vejde do dokumentace k PowerShellu. Všechny články musí být zahrnuty v tabulce obsahu (TOC). Navrhované umístění obsahu by mělo být zařazeno do diskuze o tématu.

Poznámka

Systém publikování automaticky vygeneruje obsah pro referenční materiály. Obsah nemusíte aktualizovat.

Aktualizace existujících článků

Pokud je to možné, články s referenčními informacemi o cmdletech jsou duplikovány ve všech verzích PowerShellu udržovaných v tomto úložišti. Při hlášení problému s odkazem na rutinu nebo About_ článku zobrazte seznam verzí článku, u kterých došlo k problému.

Na každou verzi souboru použijte příslušnou změnu.

Lokalizovaný obsah

Dokumentace k PowerShellu je napsaná v angličtině a přeložená do 17 dalších jazyků. Anglický obsah je uložen v úložišti GitHub s názvem MicrosoftDocs/PowerShell-Docs. Problémy zjištěné v přeloženého obsahu by se měly odeslat do tohoto úložiště.

Všechny překlady začínají nejprve z anglického obsahu. Používáme lidský i strojový překlad.

Metoda překladu Jazyky
Lidský překlad de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, zh-CN, zh-TW
Strojový překlad cs-CZ, hu-HU, nl-NL, pl-PL, pt-PT, sv-SE, tr-TR

Obsah přeložený strojový překlad nemusí vždy vést ke správnému výběru slov a gramatikě. Pokud místo technických podrobností článku zjistíte chybu v překladu pro libovolný jazyk, otevřete problém s vysvětlením, proč si myslíte, že je překlad nesprávný.

Některé problémy s překladem je možné vyřešit změnou zdrojových souborů v angličtině. Některé problémy ale můžou vyžadovat aktualizace našeho interního systému překladu. V těchto případech musíme tento problém odeslat našemu internímu lokalizačnímu týmu k revizi a odpovědi.

Další kroky

Existují dva běžné způsoby odeslání změn na GitHubu. Obě metody jsou popsány v centrálním Průvodci pro přispěvatele.

  1. V rozhraní webu GitHubu můžete provádět rychlé úpravy existujících dokumentů.
  2. Použijte úplný pracovní postup GitHubu pro přidávání nových článků, aktualizaci více souborů nebo jiných velkých změn.

Před zahájením jakýchkoli změn byste měli vytvořit fork úložiště PowerShell-Docs. Změny by měly být provedeny v pracovní větvi ve vaší kopii PowerShell-Docs. Pokud používáte metodu rychlého úprav v GitHubu, tyto kroky se za vás zpracují. Pokud používáte úplný pracovní postup GitHubu, musíte být připraveni pracovat místně.

Obě metody končí vytvořením Pull Requestu (PR). Další informace a osvědčené postupy najdete v tématu Odeslání žádosti o přijetí změn.

  • Last updated on