Jak współtworzyć dokumentację

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

Opanuj również składnia. Do podglądu artykułu podczas jego pisania możesz użyć edytor z podglądem.

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

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 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 i ewentualnie skorzystać z jednego z wielu klientów graficznych.

Dokumentację modyfikuj w ten sposób:

na GitHubie utwórz fork repozytorium nette/docs
to repozytorium sklonujesz na swój komputer
następnie w odpowiedniej gałęzi wprowadź zmiany
sprawdź zbędne spacje w tekście za pomocą narzędzia Code-Checker
zmiany zapisz (commituj)
jeśli jesteś zadowolony ze zmian, wyślij (pushnij) je na GitHub do swojego forka
stamtąd wyślij je do repozytorium nette/docs, tworząc 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. 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.