Jak współtworzyć dokumentację
*****************************

.[perex]
Współtworzenie dokumentacji jest jedną z najbardziej wartościowych czynności, ponieważ pomagasz innym zrozumieć framework.


Jak pisać?
----------

Dokumentacja jest przeznaczona przede wszystkim dla osób, które zapoznają się z tematem. Dlatego powinna spełniać kilka ważnych punktów:

- Zacznij od prostego i ogólnego. Do bardziej zaawansowanych tematów przejdź dopiero na końcu
- Staraj się jak najlepiej wyjaśnić sprawę. Spróbuj na przykład najpierw wyjaśnić temat koledze
- Podawaj tylko te informacje, które użytkownik rzeczywiście potrzebuje wiedzieć na dany temat
- Sprawdź, czy twoje informacje są rzeczywiście prawdziwe. Każdy kod przetestuj
- Bądź zwięzły - to, co napiszesz, skróć o połowę. A potem spokojnie jeszcze raz
- Oszczędzaj na wszelkiego rodzaju wyróżnieniach, od pogrubienia po ramki jak `.[note]`
- W kodach przestrzegaj [Standard kodowania |Coding Standard]

Opanuj również [składnia |syntax]. Do podglądu artykułu podczas jego pisania możesz użyć [edytor z podglądem |https://editor.nette.org/].


Wersje językowe
---------------

Podstawowym językiem jest angielski, Twoje zmiany powinny więc być w języku czeskim i angielskim. Jeśli angielski nie jest Twoją mocną stroną, użyj [DeepL Translator |https://www.deepl.com/translator], a inni sprawdzą Twój tekst.

Tłumaczenie na inne języki zostanie wykonane automatycznie po zatwierdzeniu i dopracowaniu Twojej modyfikacji.


Trywialne poprawki
------------------

Aby współtworzyć dokumentację, niezbędne jest posiadanie konta na [GitHub|https://github.com].

Najprostszym sposobem na wprowadzenie drobnej zmiany w dokumentacji jest skorzystanie z linków na końcu każdej strony:

- *Ukaž na GitHubu* otworzy źródłową postać danej strony na GitHubie. Następnie wystarczy nacisnąć przycisk `E` i można zacząć edytować (konieczne jest bycie zalogowanym na GitHubie)
- *Otevři náhled* otworzy edytor, w którym od razu widzisz również wynikowy wygląd wizualny

Ponieważ [edytor z podglądem |https://editor.nette.org/] nie ma możliwości zapisywania zmian bezpośrednio na GitHubie, konieczne jest po zakończeniu edycji skopiowanie tekstu źródłowego do schowka (przyciskiem *Copy to clipboard*), a następnie wklejenie go do edytora na GitHubie. Pod polem edycyjnym znajduje się formularz do wysłania. Tutaj nie zapomnij krótko podsumować i wyjaśnić powód swojej modyfikacji. Po wysłaniu powstanie tzw. pull request (PR), który można dalej edytować.


Większe poprawki
----------------

Bardziej odpowiednie niż korzystanie z interfejsu GitHubu jest zapoznanie się z podstawami pracy z systemem kontroli wersji Git. Jeśli nie znasz pracy z Gitem, możesz zapoznać się z przewodnikiem [git - the simple guide |https://rogerdudler.github.io/git-guide/] i ewentualnie skorzystać z jednego z wielu [klientów graficznych |https://git-scm.com/downloads/guis].

Dokumentację modyfikuj w ten sposób:

1) na GitHubie utwórz [fork |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] repozytorium [nette/docs |https://github.com/nette/docs]
2) to repozytorium [sklonujesz |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] na swój komputer
3) następnie w [odpowiedniej gałęzi |#Struktura dokumentacji] wprowadź zmiany
4) sprawdź zbędne spacje w tekście za pomocą narzędzia [Code-Checker |code-checker:]
4) zmiany zapisz (commituj)
6) jeśli jesteś zadowolony ze zmian, wyślij (pushnij) je na GitHub do swojego forka
7) stamtąd wyślij je do repozytorium `nette/docs`, tworząc [pull request|https://help.github.com/articles/creating-a-pull-request] (PR)

Jest to normalne, że będziesz otrzymywać komentarze z uwagami. Śledź proponowane zmiany i wprowadź je. Proponowane zmiany dodaj jako nowe commity i ponownie wyślij na GitHub. Nigdy nie twórz nowego pull requesta w celu modyfikacji istniejącego pull requesta.


Struktura dokumentacji
----------------------

Cała dokumentacja znajduje się na GitHubie w repozytorium [nette/docs |https://github.com/nette/docs]. Aktualna wersja jest w gałęzi master, starsze wersje znajdują się w gałęziach takich jak `doc-3.x`, `doc-2.x`.

Zawartość każdej gałęzi dzieli się na główne foldery reprezentujące poszczególne obszary dokumentacji. Na przykład `application/` odpowiada https://doc.nette.org/cs/application, `latte/` odpowiada https://latte.nette.org itd. Każdy taki folder zawiera podfoldery reprezentujące wersje językowe (`cs`, `en`, ...) oraz ewentualnie podfolder `files` z obrazkami, które można wstawiać do stron w dokumentacji.