Współtwórz dokumentację K8s

• 1: Zgłaszanie propozycji poprawy treści
• 2: Dokumentowanie funkcji nowego wydania
• 3: Przeglądanie zmian
• 4: Aktualizacja materiałów źródłowych
• 5: Styl dokumentacji
• 5.1: Typy treści
• 6: Tłumaczenie dokumentacji na język polski

1 - Zgłaszanie propozycji poprawy treści

Jeśli zauważysz problem z dokumentacją Kubernetesa lub masz pomysł na nową treść, otwórz zgłoszenie. Wszystko, czego potrzebujesz, to konto GitHub i przeglądarka internetowa.

W większości przypadków nowa praca nad dokumentacją Kubernetesa rozpoczyna się od zgłoszenia na GitHubie. Współtwórcy Kubernetesa następnie przeglądają, kategoryzują i tagują zgłoszenia. Następnie Ty lub inny członek społeczności Kubernetesa otwiera pull requesta z poprawkami rozwiązującymi problem.

Otwarcie zgłoszenia

Jeśli chcesz zasugerować ulepszenia do istniejącej treści lub zauważysz błąd, otwórz zgłoszenie.

1. Kliknij link Create an issue na prawym pasku bocznym. Przekieruje Cię to na stronę z problemem w GitHub wstępnie wypełnioną kilkoma nagłówkami.
2. Opisz problem lub sugestię poprawy. Podaj jak najwięcej szczegółów.
3. Kliknij Submit new issue.

Po przesłaniu, od czasu do czasu sprawdzaj swoje zgłoszenie lub włącz powiadomienia GitHub. Recenzenci i inni członkowie społeczności mogą zadawać pytania, zanim będą mogli podjąć działania w sprawie Twojego zgłoszenia.

Sugestia nowej treści

Jeśli masz pomysł na nowe treści, ale nie jesteś pewien, gdzie powinny się one znaleźć, możesz nadal utworzyć zgłoszenie. Wykonaj jeden z kroków:

• Wybierz istniejącą stronę w sekcji, do której Twoim zdaniem należy treść, i kliknij Create an issue.
• Przejdź do GitHub i utwórz zgłoszenie bezpośrednio.

Jak tworzyć świetne zgłoszenia

Pamiętaj o następujących rzeczach przy zgłaszaniu problemu:

• Podaj jasny opis problemu. Opisz, co konkretnie jest brakujące, nieaktualne, błędne lub wymaga poprawy.
• Wyjaśnij, jaki konkretny wpływ ma ten problem na użytkowników.
• W przypadku problemów o dużym zakresie, podziel je na mniejsze zagadnienia, aby łatwiej było nad nimi pracować. Na przykład, "Napraw dokumentację dotyczącą bezpieczeństwa" jest zbyt ogólne, ale "Dodaj szczegóły do tematu 'Ograniczanie dostępu do sieci'" jest na tyle precyzyjne, by można było podjąć działanie.
• Przeszukaj istniejące zgłoszenia, aby sprawdzić, czy jest coś związanego lub podobnego do nowego zgłoszenia.
• Jeśli nowe zgłoszenie dotyczy innego zgłoszenia lub pull requesta, odwołaj się do niego poprzez podanie pełnego adresu URL lub numeru zgłoszenia lub pull requesta poprzedzonego znakiem #. Na przykład: Introduced by #987654.
• Przestrzegaj Kodeksu postępowania. Szanuj innych współtwórców. Na przykład, "Dokumentacja jest okropna" nie jest ani pomocną ani uprzejmą opinią.

2 - Dokumentowanie funkcji nowego wydania

Każda główna wersja Kubernetesa wprowadza nowe funkcje, które wymagają dokumentacji. Nowe wersje przynoszą również aktualizacje do istniejących funkcji i dokumentacji (na przykład awansowanie funkcji z wersji alpha do beta).

Zazwyczaj SIG odpowiedzialny za funkcję przesyła szkic dokumentacji funkcji jako pull request do odpowiedniego gałęzi rozwojowej w repozytorium kubernetes/website, a ktoś z zespołu SIG Docs dostarcza uwagi redakcyjne lub edytuje szkic bezpośrednio. Ta sekcja opisuje konwencje dotyczące rozgałęzień (ang. branching) oraz proces stosowany podczas wydania przez obie grupy.

Dla współtwórców dokumentacji

Ogólnie rzecz biorąc, współtwórcy dokumentacji nie piszą treści od podstaw na potrzeby wydania. Zamiast tego współpracują z SIG tworzącym nową funkcję, aby dopracować szkic dokumentacji i przygotować go do wydania.

Po wybraniu fukncji do udokumentowania lub wsparcia, zapytaj o nią na kanale Slack #sig-docs, podczas cotygodniowego spotkania SIG Docs lub bezpośrednio w zgłoszeniu PR wystawionym przez SIG odpowiedzialny za funkcje. Jeśli otrzymasz zgodę, możesz edytować PR za pomocą jednej z technik opisanych w Wprowadź zmiany do PR innej osoby.

Dowiedz się o nadchodzących funkcjach

Aby dowiedzieć się o nadchodzących funkcjach, weź udział w cotygodniowym spotkaniu SIG Release (zobacz stronę społeczności w celu uzyskania informacji o nadchodzących spotkaniach) i monitoruj dokumentację dotyczącą wydania w repozytorium kubernetes/sig-release. Każde wydanie ma podkatalog w katalogu /sig-release/tree/master/releases/. Podkatalog zawiera harmonogram wydania, szkic notatek do wydania oraz dokument z listą każdej osoby w zespole wydania.

Harmonogram wersji zawiera linki do wszystkich innych dokumentów, spotkań, protokołów spotkań i kamieni milowych związanych z wydaniem. Zawiera również informacje o celach i harmonogramie wydania oraz wszelkich specjalnych procesach wdrożonych dla tego wydania. Pod koniec dokumentu zdefiniowano kilka terminów związanych z wydaniem.

Ten dokument zawiera również link do Arkusza śledzenia funkcji, który jest oficjalnym sposobem na poznanie wszystkich nowych funkcji planowanych do wprowadzenia w wydaniu.

Dokumentacja zespołu odpowiadającego za kolejne wydanie zawiera listę osób do przypisanych do różnych ról. Jeśli nie jest jasne, do kogo się zwrócić w sprawie konkretnej funkcji lub pytania, które masz, możesz skorzystać z jednego z dwóch rozwiązań: weź udział w spotkaniu zespołu, aby zadać swoje pytanie, lub skontaktuj się z liderem wydania, aby mógł Cię odpowiednio skierować.

Szkic notatek z wydania to dobre miejsce, aby dowiedzieć się o specyficznych funkcjach, zmianach, przestarzałych elementach i innych kwestiach dotyczących wydania. Ponieważ treść nie jest ostateczna aż do późnego etapu, warto zachować ostrożność.

Arkusz śledzenia funkcji

Arkusz śledzenia funkcji dla danej wersji Kubernetesa wymienia każdą funkcję, która jest planowana do wydania. Każdy element zawiera nazwę funkcji, link do głównego problemu na GitHubie, poziom stabilności (Alpha, Beta lub Stable), SIG i osobę odpowiedzialną za jej wdrożenie, czy wymaga dokumentacji, projekt notatki o wydaniu dla funkcji oraz czy została zintegrowana. Pamiętaj o następujących zasadach:

• Funkcje w wersji Beta i Stable są zazwyczaj priorytetowane wyżej w dokumentacji niż funkcje w wersji Alfa.
• Trudno jest przetestować (a tym samym udokumentować) funkcję, która nie została zmergowana, lub przynajmniej jest uważana za kompletną w swoim PR.
• Określenie, czy funkcja wymaga dokumentacji, jest procesem manualnym. Nawet jeśli funkcja nie jest oznaczona jako wymagająca dokumentacji, może być konieczne jej udokumentowanie.

Dla developerów lub innych członków SIG

Ta sekcja zawiera informacje dla członków innych SIG Kubernetesów dokumentujących nowe funkcje na potrzeby wydania.

Jeśli jesteś członkiem SIG, który rozwija nową funkcję dla Kubernetesa, musisz współpracować z SIG Docs, aby mieć pewność, że Twoja funkcja zostanie udokumentowana na czas przed wydaniem. Sprawdź arkusz śledzenia funkcji lub sprawdź kanał Slack Kubernetes #sig-release, aby zweryfikować szczegóły harmonogramu i terminy.

Otwórz tymczasowy PR

1. Otwórz szkic pull requestu do gałęzi dev-1.33 w repozytorium kubernetes/website, z małym commitem, który później zmienisz. Aby utworzyć szkic pull requestu, użyj rozwijanego menu Create Pull Request i wybierz Create Draft Pull Request, następnie kliknij Draft Pull Request.
2. Edytuj opis pull requesta, aby zawierał linki do PR-ów w kubernetes/kubernetes oraz zgłoszeń w kubernetes/enhancements.
3. Zostaw komentarz w powiązanym zgłoszeniu w tym repozytorium kubernetes/enhancements z linkiem do PR, aby powiadomić osobę zajmującą się dokumentacją tej wersji, że dokumentacja dotycząca funkcji jest w przygotowaniu i powinna być śledzona w tym wydaniu.

Jeśli Twoja funkcjonalność nie wymaga żadnych zmian w dokumentacji, upewnij się, że zespół sig-release o tym wie, wspominając o tym na kanale Slack #sig-release. Jeśli funkcjonalność wymaga dokumentacji, ale PR nie został utworzony, funkcjonalność może zostać usunięta z kamienia milowego.

PR gotowy do przeglądu

Kiedy będziesz gotowy, wypełnij swój tymczasowy PR dokumentacją funkcji i zmień stan PR z roboczego na ready for review. Aby oznaczyć pull request jako gotowy do przeglądu, przejdź do pola scalania (ang. merge box) i kliknij Ready for review.

Najlepiej jak potrafisz opisz swoją funkcję i sposób jej użycia. Jeśli potrzebujesz pomocy w strukturyzacji swojej dokumentacji, zapytaj na kanale Slack #sig-docs.

Gdy ukończysz swój materiał, osoba odpowiedzialna za dokumentację przypisana do Twojej funkcji go przegląda. Aby zapewnić dokładność techniczną, treść może również wymagać przeglądu technicznego przez odpowiednie SIG-i. Skorzystaj z ich sugestii, aby dopracować treść do stanu gotowego do wydania.

Jeśli twoja funkcja wymaga dokumentacji, a pierwsza wersja treści nie zostanie dostarczona, funkcja może zostać usunięta z kamienia milowego.

Bramki funkcji (ang. feature gates)

Jeśli Twoja funkcja jest funkcją Alfa lub Beta i jest włączana warunkowo bramką funkcji (ang. feature gate), potrzebujesz dla niej pliku bramki funkcji wewnątrz content/en/docs/reference/command-line-tools-reference/feature-gates/. Nazwa pliku powinna być nazwą bramki funkcji z sufiksem .md. Możesz spojrzeć na inne pliki już znajdujące się w tym samym katalogu, aby uzyskać wskazówkę, jak powinien wyglądać Twój plik. Zwykle wystarczy jeden akapit; dla dłuższych wyjaśnień dodaj dokumentację w innym miejscu i dodaj do niej link.

Aby upewnić się, że twój feature gate pojawi się w tabeli Alpha/Beta Feature gates, dodaj następujące informacje do sekcji front matter w pliku Markdown z opisem:

stages:
  - stage: <alpha/beta/stable/deprecated>  # Specify the development stage of the feature gate
    defaultValue: <true or false>     # Set to true if enabled by default, false otherwise
    fromVersion: <Version>            # Version from which the feature gate is available
    toVersion: <Version>              # (Optional) The version until which the feature gate is available

W przypadku nowych bramek funkcji wymagany jest również osobny opis bramki funkcji; utwórz nowy plik Markdown w content/en/docs/reference/command-line-tools-reference/feature-gates/ (użyj innych plików jako szablonu).

Gdy zmieniasz bramkę funkcji z domyślnie wyłączonej na domyślnie włączoną, może być konieczne zmienienie również innej dokumentacji (nie tylko listy bramek funkcji). Uważaj na zwroty takie jak „Pole exampleSetting jest polem beta i jest domyślnie wyłączone. Możesz je włączyć, włączając bramkę funkcji ProcessExampleThings.”

Jeśli Twoja funkcja osiągnęła status GA lub została oznaczona jako przestarzała, dodaj dodatkowy wpis stage w ramach bloku stages w pliku opisu. Upewnij się, że etapy Alpha i Beta pozostają nienaruszone. Ten krok przenosi bramkę funkcji z Feature gates for Alpha/Beta do Feature gates for graduated or deprecated features. Na przykład:

stages:
  - stage: alpha 
    defaultValue: false
    fromVersion: "1.12"
    toVersion: "1.12"
  - stage: beta 
    defaultValue: true
    fromVersion: "1.13"
  # Added a `toVersion` to the previous stage.
    toVersion: "1.18"
  # Added 'stable' stage block to existing stages.
  - stage: stable
    defaultValue: true
    fromVersion: "1.19"
    toVersion: "1.27"

Ostatecznie Kubernetes przestanie w ogóle uwzględniać bramę funkcji. Aby zasygnalizować usunięcie bramy funkcji, uwzględnij removed: true w przedniej części odpowiedniego pliku opisu. Wprowadzenie tej zmiany oznacza, że informacje o bramie funkcji przenoszą się z Skróty funkcji dla ukończonych lub przestarzałych funkcji do dedykowanej strony zatytułowanej Skróty funkcji (usunięte), łącznie z jej opisem.

Wszystkie PR-y zostały zrecenzowane i są gotowe do scalenia

Jeśli Twój PR nie został jeszcze scalony z gałęzią dev-1.33 przed terminem wydania, współpracuj z osobą odpowiedzialną za dokumentację i zarządzającą wydaniem, aby dodać go przed terminem. Jeśli Twoja funkcja potrzebuje dokumentacji, a dokumentacja nie jest gotowa, funkcja może zostać usunięta z bieżącego planu (milestone).

3 - Przeglądanie zmian

W tej sekcji opisano, jak dokonać przeglądu treści.

4 - Aktualizacja materiałów źródłowych

Tematy w tej sekcji opisują, jak aktualizować (czyli ponownie wygenerować) materiały źródłowe (ang. reference documentation) Kubernetesa.

Aby zbudować materiały źródłowe, zapoznaj się z następującym przewodnikiem:

• Szybki start generowania materiałów źródłowych

5 - Styl dokumentacji

Tematy w tej sekcji zawierają wskazówki dotyczące stylu pisania, formatowania treści i organizacji, a także korzystania ze specyficznych dostosowań Hugo dla dokumentacji Kubernetesa.

5.1 - Typy treści

Dokumentacja Kubernetesa obejmuje kilka typów treści stron:

• Pojęcia i koncepcje (ang. Concept)
• Zadanie (ang. Task)
• Samouczek (ang. Tutorial)
• Materiały źródłowe (ang. Reference)

Sekcje treści

Każdy typ strony zawiera szereg sekcji zdefiniowanych przez komentarze Markdown i nagłówki HTML. Możesz dodać nagłówki do swojej strony za pomocą kodu heading. Komentarze i nagłówki pomagają utrzymać odpowiednią strukturę strony dla danego typu.

Przykłady komentarzy w Markdown definiujących sekcje strony:

<!-- overview -->

<!-- body -->

Aby utworzyć typowe nagłówki na swoich stronach, użyj kodu heading z nazwą nagłówka.

Przykłady nazw nagłówków:

• whatsnext - co dalej
• prerequisites - wymagania wstępne
• objectives - cele
• cleanup - sprzątanie
• synopsis - streszczenie
• seealso - zobacz także
• options - opcje

Na przykład, aby utworzyć nagłówek whatsnext, dodaj kod nagłówka z nazwą "whatsnext":

## {{% heading "whatsnext" %}}

Możesz zadeklarować nagłówek prerequisites w następujący sposób:

## {{% heading "prerequisites" %}}

Kod heading oczekuje jednego parametru typu string. Ten parametr nagłówka odpowiada prefiksowi zmiennej w plikach i18n/<lang>/<lang>.toml. Na przykład:

i18n/en/en.toml:

[whatsnext_heading]
other = "What's next"

i18n/ko/ko.toml:

[whatsnext_heading]
other = "다음 내용"

Typy zawartości

Każdy typ zawartości nieformalnie definiuje swoją oczekiwaną strukturę strony. Twórz zawartość strony, korzystając z sugerowanych sekcji strony.

Pojęcie (ang. Concept)

Strona z pojęciami wyjaśnia określony aspekt Kubernetesa. Na przykład, strona koncepcyjna może opisywać obiekt Deployment w Kubernetesie i wyjaśniać jego rolę jako aplikacji po wdrożeniu, skalowaniu i aktualizacji. Zazwyczaj strony koncepcyjne nie zawierają instrukcji krok po kroku, lecz odsyłają do zadań lub samouczków.

Aby napisać nową stronę z pojęciem, utwórz plik Markdown w podkatalogu katalogu /content/en/docs/concepts, z następującymi sekcjami:

Strony koncepcyjne są podzielone na trzy sekcje:

Sekcje overview i body pojawiają się jako komentarze na stronie z koncepcjami. Możesz dodać sekcję whatsnext do swojej strony za pomocą kodu heading.

Wypełnij każdą sekcję treścią. Postępuj zgodnie z tymi wytycznymi:

• Organizuj treści za pomocą nagłówków H2 i H3.
• Dla overview, ustaw kontekst tematu za pomocą pojedynczego akapitu.
• Dla body wyjaśnij koncepcję.
• Dla whatsnext, podaj wypunktowaną listę tematów (maksymalnie 5), aby dowiedzieć się więcej o koncepcji.

Strona adnotacje jest opublikowanym przykładem strony koncepcyjnej.

Zadanie (ang. Task)

Strony opisujące wykonywanie zadań zawierają minimum wyjaśnień, ale zwykle podają odnośniki do dokumentacji objaśniającej pojęcia i szerszy kontekst danego tematu.

Aby napisać nową stronę zadania, utwórz plik Markdown w podkatalogu katalogu /content/en/docs/tasks, z następującymi sekcjami:

Sekcje overview, steps i discussion pojawiają się jako komentarze na stronie zadania. Możesz dodać sekcje prerequisites i whatsnext do swojej strony za pomocą kodu heading.

Każdą sekcję uzupełnij treścią. Użyj następujących wytycznych:

• Użyj nagłówków poziomu H2 lub niższego (z dwoma wiodącymi znakami #). Sekcje są automatycznie tytułowane przez szablon.
• Dla overview użyj akapitu, aby ustawić kontekst dla całego tematu.
• Dla prerequisites używaj list punktowanych, kiedy to możliwe. Zaczynaj dodawać dodatkowe wymagania wstępne poniżej include. Domyślne wymagania wstępne obejmują działający klaster Kubernetesa.
• Dla steps używaj numerowanych list.
• Do omówienia użyj standardowej treści, aby rozwinąć informacje zawarte w sekcji steps.
• Dla whatsnext, podaj listę punktowaną z maksymalnie 5 tematami, które mogą zainteresować czytelnika jako kolejne tematy do przeczytania.

Przykład opublikowanego tematu zadania to Korzystanie z proxy HTTP do uzyskania dostępu do API Kubernetesa.

Samouczek (ang. Tutorial)

Strona samouczka pokazuje, jak osiągnąć cel, który jest bardziej złożony niż pojedyncze zadanie. Zazwyczaj strona samouczka składa się z kilku sekcji, z których każda zawiera sekwencję kroków. Na przykład samouczek może przeprowadzać użytkownika przez przykładowy kod ilustrujący określoną funkcję Kubernetesa. Samouczki mogą zawierać ogólne wyjaśnienia, ale powinny odsyłać do powiązanych tematów koncepcyjnych w celu dogłębnego omówienia zagadnienia.

Aby napisać nową stronę samouczka, utwórz plik Markdown w podkatalogu katalogu /content/en/docs/tutorials, z następującymi sekcjami:

Sekcje overview, objectives i lessoncontent pojawiają się jako komentarze na stronie samouczka. Możesz dodać sekcje prerequisites, cleanup i whatsnext do swojej strony za pomocą kodu heading.

Każdą sekcję uzupełnij treścią. Użyj następujących wytycznych:

• Użyj nagłówków poziomu H2 lub niższego (z dwoma wiodącymi znakami #). Sekcje są automatycznie tytułowane przez szablon.
• Dla overview użyj akapitu, aby ustawić kontekst dla całego tematu.
• W przypadku prerequisites używaj, jeśli to możliwe, list punktowanych. Dodaj dodatkowe wymagania wstępne poniżej tych domyślnie uwzględnionych.
• Dla objectives, używaj list wypunktowanych.
• Dla lessoncontent, użyj mieszanki list numerowanych i treści narracyjnej w zależności od potrzeb.
• W przypadku cleanup, użyj numerowanych list, aby opisać kroki niezbędne do posprzątania stanu klastra po zakończeniu zadania.
• Dla whatsnext, podaj listę punktowaną z maksymalnie 5 tematami, które mogą zainteresować czytelnika jako kolejne tematy do przeczytania.

Przykładem opublikowanego tematu samouczka jest Uruchamianie aplikacji bezstanowej przy użyciu Deployment.

Materiały źródłowe (ang. Reference)

Każde narzędzie Kubernetesa ma swoją stronę materiałów źródłowych (ang. reference page), gdzie można znaleźć jego opis i listę dostępnych opcji. Dokumentacja ta jest generowana przez skrypty, które automatycznie pobierają informacje z poleceń narzędzia.

Strona z odniesieniem do narzędzia ma kilka możliwych sekcji:

Przykłady opublikowanych stron referencyjnych narzędzi to:

• kubeadm init
• kube-apiserver
• kubectl

Co dalej?

• Dowiedz się więcej o Przewodniku stylu
• Dowiedz się więcej o Przewodniku treści
• Dowiedz się więcej o organizacji treści

6 - Tłumaczenie dokumentacji na język polski

Na tej stronie znajdziesz wskazówki i wytyczne przydatne przy tłumaczeniu dokumentacji Kubernetesa na język polski.

Dokumentem nadrzędnym jest angielski opis stylu dokumentacji.

Wskazówki ogólne

Staramy się, aby styl tłumaczenia był jak najbardziej naturalny. W przypadku dokumentacji technicznej może być to trudne zadanie, szczególnie gdy chcemy utrzymać precyzję tłumaczenia. Zależy nam na unikaniu sytuacji, kiedy tekst zaczyna sprawiać wrażenie przetłumaczonego maszynowo.

Pamiętajmy też, że oficjalna wykładnia zawsze znajduje się w tekście angielskim. Polskie tłumaczenie ma ułatwić pierwsze kroki osobom, które zaczynają swoją przygodę z Kubernetesem.

Wytyczne szczegółowe

Odmiana terminu Kubernetes

Kubernetes jest nazwą własną, liczba pojedyncza, rodzaj męski. Odmieniamy: Kubernetesa, Kubernetesem itp. W uzasadnionych przypadkach można stosować też "system Kubernetes".

Odmiana terminów Pod, Deployment

Odmieniamy zgodnie z ogólnymi zasadami - poda, deploymentu itp.

Ujednolicony słownik

W sieci dostępne są słowniki terminów informatycznych. Poniższa tabela zawiera słowa specyficzne dla Kubernetesa i inne często używane wyrażenia.