Wprowadzenie do współtworzenia dokumentacji programu PowerShell

Ten artykuł zawiera omówienie sposobu rozpoczynania pracy jako współautora dokumentacji programu PowerShell.

struktura PowerShell-Docs

Istnieją trzy kategorie zawartości w repozytorium PowerShell-Docs:

• zawartość referencyjna
• zawartość koncepcyjna
• pliki metadanych i konfiguracji

Zawartość referencyjna

Zawartość referencyjna to odniesienie do cmdletów dostępnych w PowerShell. Polecenie cmdlet reference jest zgrupowane w folderach wersji (takich jak 5.1, 7.4, 7.5 i 7.6), które zawierają dokumentację dla modułów dostarczanych z programem PowerShell. Ta zawartość jest również używana do tworzenia informacji pomocy wyświetlanych przez cmdlet Get-Help.

Zawartość koncepcyjna

Dokumentacja koncepcyjna nie jest zorganizowana według wersji. Wszystkie artykuły są wyświetlane dla każdej wersji programu PowerShell.

Notatka

Za każdym razem, gdy artykuł koncepcyjny zostanie dodany, usunięty lub zmieniono jego nazwę, należy zaktualizować spis treści. Wszystkie usunięte lub zmienione nazwy plików muszą zostać przekierowane.

Pliki metadanych

Ten projekt zawiera kilka typów plików metadanych. Pliki metadanych kontrolują zachowanie naszych narzędzi kompilacji i systemu publikowania. Tylko opiekunowie PowerShell-Docs i zatwierdzeni współautorzy mogą dokonywać zmian w tych plikach. Jeśli uważasz, że plik meta powinien zostać zmieniony, otwórz problem, aby omówić potrzebne zmiany.

Pliki meta w katalogu głównym repozytorium

• .* — pliki konfiguracyjne w katalogu głównym repozytorium
• *.md — dokumentacja projektu w głównej lokalizacji repozytorium
• *.yml — dokumentacja projektu w głównej lokalizacji repozytorium
• .devcontainer/* — pliki konfiguracji devcontainer
• .github/**/* — szablony, akcje i inne pliki meta usługi GitHub
• .vscode/**/* — konfiguracje rozszerzeń programu VS Code
• assets/* — zawiera pliki do pobrania połączone w dokumentacji
• redir/* — zawierają pliki mapowania przekierowania
• tests/* — narzędzia testowe używane przez system kompilacji
• tools/* — inne narzędzia używane przez system kompilacji

Pliki meta w zestawie dokumentacji

• reference/**/*.json — pliki konfiguracji zestawu dokumentów
• reference/**/*.yml — spis treści i inne pliki zawartości ustrukturyzowanej
• reference/bread/* — konfiguracja nawigacji okruszkowej
• reference/includes/* — pliki zawierające markdown
• reference/mapping/* — konfiguracja mapowania wersji
• reference/**/media/** — pliki obrazów używane w dokumentacji
• reference/module/* — konfiguracja strony przeglądarki modułów

Tworzenie nowych artykułów

Dla każdego nowego dokumentu, który chcesz współtworzyć, należy utworzyć problem z usługą GitHub. Sprawdź istniejące problemy, aby upewnić się, że nie duplikujesz wysiłków. Przypisane problemy są uważane za in progress. Jeśli chcesz współpracować nad problemem, skontaktuj się z osobą przypisaną do problemu.

Podobnie jak w przypadku procesu RFC programu PowerShell, utwórz problem przed zapisaniem zawartości. Problem gwarantuje, że nie tracisz czasu i wysiłku na pracę, która zostanie odrzucona przez zespół PowerShell-Docs. Kwestia ta umożliwia nam skonsultowanie się z Tobą w sprawie zakresu treści oraz jej umiejscowienia w dokumentacji programu PowerShell. Wszystkie artykuły muszą być zawarte w spisie treści . Proponowana lokalizacja spisu treści powinna zostać uwzględniona w dyskusji na temat problemu.

Notatka

System publikowania automatycznie generuje spis treści dla treści referencyjnych. Nie musisz aktualizować spisu treści.

Aktualizowanie istniejących artykułów

W stosownych przypadkach, artykuły referencyjne dotyczące poleceń cmdlet są duplikowane we wszystkich wersjach programu PowerShell obsługiwanych w tym repozytorium. Podczas zgłaszania problemu dotyczącego odwołania do cmdletu lub artykułu About_, wymień wersje artykułu, które mają problem.

Zastosuj odpowiednią zmianę do każdej wersji pliku.

Zlokalizowana zawartość

Dokumentacja programu PowerShell jest napisana w języku angielskim i przetłumaczona na 17 innych języków. Zawartość w języku angielskim jest przechowywana w repozytorium GitHub o nazwie MicrosoftDocs/PowerShell-Docs. Problemy znalezione w przetłumaczonej zawartości powinny zostać przesłane do tego repozytorium.

Wszystkie tłumaczenia zaczynają się od pierwszej zawartości w języku angielskim. Używamy zarówno tłumaczeń ludzkich, jak i maszynowych.

Metoda tłumaczenia	Języki
Tłumaczenie ludzkie	de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, zh-CN, zh-TW
Tłumaczenie maszynowe	cs-CZ, hu-HU, nl-NL, pl-PL, pt-PT, sv-SE, tr-TR

Zawartość przetłumaczona przez tłumaczenie maszynowe może nie zawsze powodować poprawne wybory słów i gramatykę. Jeśli znajdziesz błąd w tłumaczeniu dla dowolnego języka, a nie w szczegółach technicznych artykułu, otwórz problem wyjaśniający, dlaczego tłumaczenie jest błędne.

Niektóre problemy z tłumaczeniem można rozwiązać przez zmianę plików źródłowych w języku angielskim. Jednak niektóre problemy mogą wymagać aktualizacji naszego wewnętrznego systemu tłumaczenia. W takich przypadkach musimy przesłać problem do naszego wewnętrznego zespołu lokalizacji w celu przejrzenia i odpowiedzi.

Następne kroki

Istnieją dwa typowe sposoby przesyłania zmian w usłudze GitHub. Obie metody są opisane w centralnym przewodniku współautora:

1. W interfejsie internetowym usługi GitHub można wprowadzić szybkie edycje istniejących dokumentów.
2. Użyj pełnego przepływu pracy GitHub do dodawania nowych artykułów, aktualizowania wielu plików lub innych dużych zmian.

Przed rozpoczęciem wprowadzania zmian należy utworzyć fork repozytorium PowerShell-Docs. Zmiany powinny zostać wprowadzone w gałęzi roboczej w kopii programu PowerShell-Docs. Jeśli używasz metody szybkiej edycji w usłudze GitHub, te kroki są obsługiwane. Jeśli używasz pełnego przepływu pracy usługi GitHub, musisz być skonfigurowany, aby móc pracować lokalnie.

Obie metody kończą się utworzeniem Pull Requesta (PR). Aby uzyskać więcej informacji i najlepszych rozwiązań, zobacz Przesyłanie żądania ściągnięcia.