Wprowadzenie współtworzenia dokumentacji programu PowerShell
W tym artykule omówiono sposób rozpoczynania pracy jako współautor dokumentacji programu PowerShell.
struktura PowerShell-Docs
Repozytorium PowerShell-Docs jest podzielone na dwie grupy zawartości: odwołanie i koncepcyjne.
Dokumentacja
Zawartość referencyjna to dokumentacja poleceń cmdlet programu PowerShell dla poleceń cmdlet, które są dostarczane w programie PowerShell.
Odwołanie jest zbierane w folderach wersji (5.1, 7.0, 7.1 i 7.2). Ta zawartość zawiera odwołanie do poleceń cmdlet tylko dla modułów, które są dostarczane za pomocą programu PowerShell. Ta zawartość służy również do tworzenia informacji pomocy wyświetlanych przez Get-Help polecenie cmdlet.
Zawartość koncepcyjna
Dokumentacja koncepcyjna zawiera następującą zawartość:
- Informacje o wersji
- Instrukcje dotyczące instalacji
- Przykładowe skrypty i artykuły z instrukcjami
- Dokumentacja DSC
- Dokumentacja zestawu SDK
Dokumentacja koncepcyjna nie jest zorganizowana według wersji. Wszystkie artykuły są wyświetlane dla każdej wersji programu PowerShell. Pracujemy nad tworzeniem artykułów specyficznych dla wersji.
Uwaga
W dowolnym momencie dodania, usunięcia lub zmiany nazwy artykułu koncepcyjnego należy zaktualizować i dołączyć do żądania ściągnięcia.
Tworzenie nowych artykułów
Dla każdego nowego dokumentu, który chcesz współtworzyć, należy utworzyć problem GitHub. Sprawdź istniejące problemy, aby upewnić się, że nie są duplikowanie 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 zapewnia, że nie tracisz czasu i wysiłku na pracę, która zostanie odrzucona przez zespół PowerShell-Docs. Problem pozwala nam skonsultować się z Tobą w zakresie zawartości i miejscu, w którym pasuje do dokumentacji programu PowerShell. Wszystkie artykuły muszą być zawarte w spisie treści (TOC). Proponowana lokalizacja toC powinna zostać uwzględniona w dyskusji na temat problemu.
Uwaga
Spis treści referencyjnych jest automatycznie generowany przez system publikowania. Nie musisz aktualizować toc.
Aktualizowanie istniejących artykułów
Jeśli ma to zastosowanie, artykuły referencyjne poleceń cmdlet są zduplikowane we wszystkich wersjach programu PowerShell przechowywanych w tym repozytorium. Podczas zgłaszania problemu dotyczącego odwołania do polecenia cmdlet lub About_ artykułu należy określić, które wersje mają wpływ na problem. Szablon problemu w GitHub zawiera listę kontrolną wersji. Użyj pól wyboru, aby określić, które wersje zawartości mają wpływ.
Sprawdź całą wersję artykułu, aby sprawdzić, czy ta sama zmiana jest potrzebna w innych wersjach. 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ść języka angielskiego jest przechowywana w repozytorium GitHub o nazwie MicrosoftDocs/PowerShell-Docs. Zlokalizowana zawartość jest przechowywana w osobnym repozytorium dla każdego języka. Repozytoria używają tej samej nazwy bazowej, ale dodaj do końca nazwę ustawień regionalnych. Na przykład MicrosoftDocs/PowerShell-Docs.de-de zawiera zawartość przetłumaczoną na język niemiecki.
Ogólnie rzecz biorąc, problemy i zmiany powinny zostać przesłane do repozytorium w języku angielskim. Wszystkie tłumaczenia zaczynają się od pierwszej zawartości w języku angielskim. Używamy zarówno tłumaczenia ludzkiego, jak i maszynowego.
| 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 translacji dla dowolnego języka, a nie w szczegółach technicznych artykułu, otwórz problem w zlokalizowanym repozytorium. Wyjaśnij, dlaczego uważasz, że tłumaczenie jest nieprawidłowe. Nasz zespół lokalizacji przegląda te problemy i reaguje na te problemy.
Następne kroki
Istnieją dwa typowe sposoby przesyłania zmian w GitHub. Obie metody opisano w centralnym przewodniku współautora:
- Możesz tworzyć szybkie edycje istniejących dokumentów w interfejsie internetowym GitHub.
- 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ć rozwidlenie repozytorium PowerShell-Docs. Zmiany powinny zostać wprowadzone w gałęzi roboczej w kopii witryny PowerShell-Docs. Jeśli używasz metody szybkiej edycji w GitHub, te kroki są obsługiwane. Jeśli używasz pełnego przepływu pracy GitHub, musisz skonfigurować go do pracy lokalnie.
Obie metody kończą się tworzeniem żądania ściągnięcia (PR). Aby uzyskać więcej informacji i najlepszych rozwiązań, zobacz Przesyłanie żądania ściągnięcia .
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla