Współtwórz dokumentację K8s

• 1: Zgłaszanie propozycji poprawy treści
• 2: Przeglądanie zmian
• 3: Aktualizacja materiałów źródłowych
• 4: Styl dokumentacji
• 4.1: Typy treści
• 5: 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 - Przeglądanie zmian

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

3 - 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

4 - 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.

4.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>.toml. Na przykład:

`i18n/en.toml`:`

[whatsnext_heading]
other = "What's next"

i18n/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 Kubernetes.
• 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

5 - 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.