Merge pull request #49668 from dkarczmarski/dkarczmarski/pl-docs-contribute-style-page-content-types.md
[pl] docs/contribute/style/page-content-types.md
This commit is contained in:
Kubernetes Prow Robot
GitHub
commit
08a367adca
|
|
@ -0,0 +1,218 @@
|
|||
---
|
||||
title: Typy treści
|
||||
content_type: concept
|
||||
weight: 80
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
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)
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Sekcje treści {#content-sections}
|
||||
|
||||
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:
|
||||
|
||||
```markdown
|
||||
<!-- overview -->
|
||||
```
|
||||
|
||||
```markdown
|
||||
<!-- 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":
|
||||
|
||||
```none
|
||||
## {{%/* heading "whatsnext" */%}}
|
||||
```
|
||||
|
||||
Możesz zadeklarować nagłówek `prerequisites` w następujący sposób:
|
||||
|
||||
```none
|
||||
## {{%/* 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`:` ``
|
||||
|
||||
```toml
|
||||
[whatsnext_heading]
|
||||
other = "What's next"
|
||||
```
|
||||
|
||||
`i18n/ko.toml`:
|
||||
|
||||
```toml
|
||||
[whatsnext_heading]
|
||||
other = "다음 내용"
|
||||
```
|
||||
|
||||
## Typy zawartości {#content-types}
|
||||
|
||||
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) {#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:
|
||||
|
||||
| Sekcja strony |
|
||||
|------------------------------|
|
||||
| overview - przegląd |
|
||||
| body - treść |
|
||||
| whatsnext - co dalej |
|
||||
|
||||
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](/docs/concepts/overview/working-with-objects/annotations/) jest opublikowanym przykładem strony koncepcyjnej.
|
||||
|
||||
### Zadanie (ang. Task) {#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:
|
||||
|
||||
| Sekcja strony |
|
||||
|------------------------------|
|
||||
| overview - przegląd |
|
||||
| prerequisites - wymagania wstępne |
|
||||
| steps - kroki |
|
||||
| discussion - dyskusja |
|
||||
| whatsnext - co dalej |
|
||||
|
||||
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](/docs/tasks/extend-kubernetes/http-proxy-access-api/).
|
||||
|
||||
### Samouczek (ang. Tutorial) {#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:
|
||||
|
||||
| Sekcja strony |
|
||||
|------------------------------|
|
||||
| overview - przegląd |
|
||||
| prerequisites - wymagania wstępne |
|
||||
| objectives - cele |
|
||||
| lessoncontent - treść lekcji |
|
||||
| cleanup - sprzątanie |
|
||||
| whatsnext - co dalej |
|
||||
|
||||
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](/docs/tasks/run-application/run-stateless-application-deployment/).
|
||||
|
||||
### Materiały źródłowe (ang. Reference) {#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:
|
||||
|
||||
| Sekcja strony |
|
||||
|------------------------------|
|
||||
| streszczenie |
|
||||
| opcje |
|
||||
| opcje z nadrzędnych poleceń |
|
||||
| przykłady |
|
||||
| zobacz także |
|
||||
|
||||
Przykłady opublikowanych stron referencyjnych narzędzi to:
|
||||
|
||||
- [kubeadm init](/docs/reference/setup-tools/kubeadm/kubeadm-init/)
|
||||
- [kube-apiserver](/docs/reference/command-line-tools-reference/kube-apiserver/)
|
||||
- [kubectl](/docs/reference/kubectl/kubectl/)
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
- Dowiedz się więcej o [Przewodniku stylu](/docs/contribute/style/style-guide/)
|
||||
- Dowiedz się więcej o [Przewodniku treści](/docs/contribute/style/content-guide/)
|
||||
- Dowiedz się więcej o [organizacji treści](/docs/contribute/style/content-organization/)
|
||||
Loading…
Reference in New Issue