Wytyczne do pisania artykułów

Nazwa i lokacja pliku

• pliki umieszczamy w folderze adekwatnym do szkolenia, zgodnie z przykładem:
  • meteorologia z modułu basic: docs/basic/meteorology
  • identyfikacja statków powietrznych z modułu S2: docs/s2/identification
• używamy rozszerzenia .mdx
• pliki i foldery nazywamy po angielsku
• nazwa pliku zaczyna się od dwucyfrowej liczby (00, 01, 02...), nawet jeśli w folderze znajduje się jeden artykuł: 00-meteorology.mdx
• jeśli załączamy obrazy, to należy umieścić je w podfolderze assets utworzonym w tym samym folderze, co plik z artykułem. Nazwa pliku graficznego powinna zaczynać się od dwucyfrowej liczby odpowiadającej nazwie pliku tekstowego, w którym wystepuje. Nazwy powinna odzwierciedlać zawartość pliku, np.:
  • docs/basic/meteorology/assets/00-cold-front.jpg
  • docs/basic/meteorology/assets/00-windshear.jpg
  • docs/s2/identification/assets/03-radar-dome.png
    W takim wypadku link do obrazu w pliku .mdx będzie miał następującą postać:
  • ![Zimny front](assets/00-cold-front.jpg)

Akapity

• nie numerujemy akapitów żadnego poziomu
• # używany jako tytuł artykułu tylko na początku dokumentu
• Tekst akapitu oznaczonego jako # jest przez Docusaurus używany w menu po lewej stronie, powinien więc być możliwie krótki
• ##, ### używamy do akapitów sekcji dokumentu
• nie pomijamy w tekście poziomów akapitów, tzn # a następnie ###
• Unikajmy długich bloków tekstu. Jeśli sekcja jest długa (+/- 300 słów) należy dla czytelności podzielić ją na subsekcje

Dla wizualizacji, tak wygląda 300 słów:

Lorem ipsum dolor sit amet consectetur adipiscing elit quisque faucibus ex sapien vitae pellentesque sem placerat in id cursus mi pretium tellus duis convallis tempus leo eu aenean sed diam urna tempor pulvinar vivamus fringilla lacus nec metus bibendum egestas iaculis massa nisl malesuada lacinia integer nunc posuere ut hendrerit semper vel class aptent taciti sociosqu ad litora torquent per conubia nostra inceptos himenaeos orci varius natoque penatibus et magnis dis parturient montes nascetur ridiculus mus donec rhoncus eros lobortis nulla molestie mattis scelerisque maximus eget fermentum odio phasellus non purus est efficitur laoreet mauris pharetra vestibulum fusce dictum risus blandit quis suspendisse aliquet nisi sodales consequat magna ante condimentum neque at luctus nibh finibus facilisis dapibus etiam interdum tortor ligula congue sollicitudin erat viverra ac tincidunt nam porta elementum a enim euismod quam justo lectus commodo augue arcu dignissim velit aliquam imperdiet mollis nullam volutpat porttitor ullamcorper rutrum gravida cras eleifend turpis fames primis vulputate ornare sagittis vehicula praesent dui felis venenatis ultrices proin libero feugiat tristique accumsan maecenas potenti ultricies habitant morbi senectus netus suscipit auctor curabitur facilisi cubilia curae hac habitasse platea dictumst lorem ipsum dolor sit amet consectetur adipiscing elit quisque faucibus ex sapien vitae pellentesque sem placerat in id cursus mi pretium tellus duis convallis tempus leo eu aenean sed diam urna tempor pulvinar vivamus fringilla lacus nec metus bibendum egestas iaculis massa nisl malesuada lacinia integer nunc posuere ut hendrerit semper vel class aptent taciti sociosqu ad litora torquent per conubia nostra inceptos himenaeos.

Numerowane listy

Format .md używa tzw. leniwego numerowania. Oznacza to, że taki zapis w pliku:

1. raz
1. dwa
1. trzy
    1. cztery
    1. pięć

Zostanie skonwertowany na poprawną numerację:

1. raz
2. dwa
3. trzy
   1. cztery
   2. pięć

W związku z tym zaleca się używac samych jedynek. I tak zostanie to zrenderowane poprawnie, a potencjalnie oszczędzi trochę manualnych poprawek, jeśli zdecydujemy się dodać punkt w środku długiej listy

Linki

Możliwe jest linkowanie do innych dokumentów w ramach naszego wiki łącznie ze wskazaniem konkretnego akapitu, przykładowo zapis:

[Lotniska - Gdzie szukać informacji?](/docs/s1/00-aerodromes.mdx#gdzie-szukać-informacji)

wygeneruje następujący link: Lotniska - Gdzie szukać informacji?

Docusaurus zamienia tytuły akapitów na linki do subsekcji zastępując spacje myślnikami, więc akapit pt. "Gdzie szukać informacji" zamieni się w #gdzie-szukać-informacji. Wielkość liter jest ignorowana, ale polskie znaki muszą być zachowane.

Struktura artykułu

Artykuły powinny w miarę możliwości odzwierciedlać następujący układ:

1. Wprowadzenie (1–3 zdania) - co to jest i dlaczego to ważne dla czytelnika
2. Definicje (jeśli potrzebne)
3. Procedura / zasada - sedno artykułu
4. Przykład - zwłaszcza jeśli w grę wchodzi frazeologia radiowa
5. Wyjątki / częste błędy (jeśli dotyczy)
6. Zobacz też / Źródła - linki do powiązanych artykułów

Admonicje (info / caution / tip)

Docusaurus wspiera bloki :::note, :::info, :::tip, :::caution, :::warning, :::danger. Używamy ich zamiast zwykłych akapitów, kiedy chcemy wyraźnie wyróżnić dygresję, wyjątek lub coś krytycznego z punktu widzenia bezpieczeństwa:

:::caution
**Ważne:** Jeśli w pobliżu lotniska jest inny ruch VFR, musisz poinformować o nim pilota podchodzącego statku.
:::

Da to następujący efekt:

caution

Ważne: Jeśli w pobliżu lotniska jest inny ruch VFR, musisz poinformować o nim pilota podchodzącego statku.

Nie nadużywamy - jeśli w artykule jest więcej niż 3–4 admonicje, prawdopodobnie tekst główny jest źle zorganizowany.

Definicje, cytaty, przykłady

Definicje, cytaty i przykłady wyróżniamy po zanku >, wszczególności przykłady frazeologii lotniczej i transmisji kontroler-pilot:

ATC: SP-ABC, Kraków Wieża, masz zgodę na lot do EPWA (...)
ATC: SP-ABC, Kraków Tower, cleared for flight to EPWA (...)

PILOT: Line up and wait runway 25, SP-ABC.
PILOT: Zajmuję pas 25 i oczekuję, SP-ABC.

tip

Aby wymusić łamanie wiersza należy posiłkować się znacznikami z HTML, tu przyda się tag <br/>, więc zapis powyższego przykładu powinien w treści wyglądać tak:

> **ATC:** SP-ABC, Kraków Wieża, masz zgodę na lot do EPWA (...) <br/>
> **ATC:** SP-ABC, Kraków Tower, cleared for flight to EPWA (...)

Przytaczanie innych źródeł, ilustracje

Nie ma przeszkód, żeby 1:1 kopiować całe frazy i akapity z przepisów prawa, czyli: polskich ustaw i rozporządzeń, prawa Unii Europejskiej (np. SERA) i umow międzynarodowych (konwencja chicagowska z załącznikami). Polskie prawo autorskie nie chroni obowiązujących przepisów ani ich urzędowych projektów.

Ten wyjątek nie dotyczy jednak innych ważnych źródeł, w tym AIP. Przykładowo, zdaniem Polskiej Agencji Żeglugi Powietrznej produkty AIP są chronione prawem autorskim. Przyjmując, że stanowisko PAŻP jest poprawne, oznacza to dwie możliwości: albo zgoda na wykorzystanie takich materiałów, albo działanie w ramach tego, na co pozwala prawo autorskie bez proszenia o zgodę. W tym ostatnim wypadku musimy jednak przestrzegać warunków prawa cytatu, które pozwala co prawda przytaczać cudze materiały chronione prawem autorskim, ale pod warunkami. Aby uniknąć problemów, pisząc artykuły zawierające przytoczenia musimy przestrzegać kilku zasad:

• Cytat musi być wyraźnie widoczny. W przypadku ilustracji nie jest to problematyczne. W przypadku przytaczania tekstu pamiętaj, by przytoczenia "brać w cudzysłów".
• Nasz cytat ma być dodatkiem, a nie zasadniczym elementem naszego artykułu.
• Powinniśmy cytować tylko urywki. Nie wklejamy całych artykułów ani całych mapek, a jedynie te ich fragmenty, które są nam potrzebne, by wyjaśnić jakiś koncept. Przytaczamy tyle, ile potrzebujemy, by osiągnąć nasz cel, ale nie więcej. Wyjątek dotyczy fotografii i utworów plastycznych (np. rysunki), które wolno przytaczać w całości.
• Naszym celem jest wyjaśnianie. Przytaczajmy wtedy, gdy bez zapoznania się z cudzymi treściami (np. fragmentem mapy) nasze wywody byłyby mniej jasne. Oznacza to, że nie powinniśmy przytaczać cudzych treści, jeśli miałoby to służyć tylko estetyce.
• Oznaczamy źródło (a jeśli je znamy, także imię i nazwisko twórcy). W przypadku AIP znamy tylko źródło, więc oznaczajmy je w konwencji Źródło: AIP <część>, <artykuł>, <data>, np. AIP IFR, AD 2 EPKK 13-1, 16.4.2026

Przestrzegając powyższych wymogów, działamy w ramach dopuszczonych przez art. 29 ustawy o prawie autorskim i prawach pokrewnych.

Alternatywą dla prawa cytatu jest wykorzystanie materiałów, w tym ilustracji, dostępnych na otwartych licencjach, takich jak Creative Commons (np. materiały dostępne w Wikimedia Commons). Wówczas jednak też musimy spełnić pewne obowiązki, wynikające z danej licencji. Jeśli wykorzystujemy zdjęcie na licencji CC, prawie zawsze minimum to wskazanie twórcy (tak, jak ta osoba jest podpisana pod utworem), podać nazwę licencji oraz link do niej (np. CC BY 4.0. Zachowajmy ostrożność przy przerabianiu dla potrzeby wiki tekstów udostępnianych na licencjach CC. Niektóre z nich, takie jak artykuły na wikipedii, wymagają wówczas udostępnienia przeróbki na konkretnych warunkach licencyjnych. W razie wątpliwości, zapytaj ACCPL62 lub ACCPL2.

Artykuł wzorcowy

sekcja 'Kontrola Ground' do dopracowania i wykorzystania jako artykuł wzorcowy w kwestii szczegółowości i stylu pisania