Kontrybuowanie do dokumentacji

Kontrybuowanie do dokumentacji to jedna z najcenniejszych czynności, bo pomaga innym zrozumieć framework.

Jak pisać?

Dokumentacja przeznaczona jest przede wszystkim dla osób, które są w danym temacie nowe. Powinna więc spełniać kilka ważnych punktów:

• Zaczynaj od prostych i ogólnych pojęć. Do bardziej zaawansowanych tematów przechodź dopiero na końcu.
• Staraj się wyjaśnić temat jak najjaśniej. Spróbuj na przykład wyjaśnić go najpierw koledze.
• Podawaj tylko te informacje, których użytkownik faktycznie potrzebuje w danym temacie.
• Weryfikuj, czy Twoje informacje są prawdziwe. Testuj każdy kawałek kodu.
• Bądź zwięzły, skróć to, co napisałeś, o połowę. A potem śmiało zrób to jeszcze raz.
• Używaj wyróżnień oszczędnie, od pogrubionego tekstu po ramki jak .[note].
• W przykładach kodu trzymaj się standardu kodowania.

Poznaj też składnię. Do podglądu artykułu w trakcie pisania możesz użyć edytora z podglądem.

Wersje językowe

Angielski jest językiem podstawowym, więc Twoje zmiany powinny być najlepiej po angielsku. Jeśli angielski nie jest Twoją mocną stroną, użyj DeepL Translatora, a inni Twój tekst przejrzą.

Tłumaczenie na pozostałe języki zostanie wykonane automatycznie po zatwierdzeniu i sfinalizowaniu Twojej poprawki.

Drobne poprawki

Żeby kontrybuować do dokumentacji, musisz mieć konto na GitHubie.

Najprostszym sposobem na wprowadzenie drobnej zmiany w dokumentacji jest użycie odnośników na końcu każdej strony:

• Pokaż na GitHubie otwiera źródłową wersję strony na GitHubie. Potem wystarczy nacisnąć klawisz E, żeby zacząć edycję (musisz być zalogowany na GitHubie).
• Otwórz podgląd otwiera edytor, w którym od razu widzisz ostateczny wygląd wizualny.

Ponieważ edytor z podglądem nie potrafi zapisywać zmian bezpośrednio na GitHuba, po zakończeniu edycji musisz skopiować tekst źródłowy do schowka (przyciskiem Kopiuj do schowka), a potem wkleić go do edytora na GitHubie. Pod polem edycji jest formularz wysyłania. Tutaj nie zapomnij krótko podsumować i wyjaśnić powodu swojej poprawki. Po wysłaniu tworzony jest pull request (PR), który można dalej edytować.

Większe poprawki

Zamiast polegać wyłącznie na interfejsie GitHuba, lepiej znać podstawy pracy z systemem kontroli wersji Git. Jeśli nie znasz Gita, możesz zajrzeć do git – the simple guide i rozważyć użycie jednego z wielu dostępnych klientów graficznych.

Dokumentację edytuj tak:

1. Na GitHubie utwórz fork repozytorium nette/docs.
2. Sklonuj to repozytorium na swój komputer.
3. Następnie wprowadź zmiany w odpowiedniej gałęzi.
4. Sprawdź nadmiarowe spacje w tekście narzędziem Code-Checker.
5. Zapisz (zacommituj) zmiany.
6. Jeśli jesteś zadowolony ze zmian, wypchnij je na GitHuba do swojego forka.
7. Stamtąd zgłoś je do repozytorium nette/docs, tworząc pull request (PR).

Często dostaje się komentarze z sugestiami. Śledź proponowane zmiany i uwzględniaj je. Proponowane zmiany dodawaj jako nowe commity i wypychaj je znowu na GitHuba. Nigdy nie twórz nowego pull requesta tylko po to, żeby zmodyfikować istniejący.

Struktura dokumentacji

Cała dokumentacja znajduje się na GitHubie w repozytorium nette/docs. Aktualna wersja jest w gałęzi master, a starsze wersje leżą w gałęziach takich jak doc-3.x, doc-2.x.

Zawartość każdej gałęzi podzielona jest na główne foldery reprezentujące poszczególne obszary dokumentacji. Na przykład application/ odpowiada https://doc.nette.org/en/application, latte/ odpowiada https://latte.nette.org itd. Każdy z tych folderów zawiera podfoldery reprezentujące wersje językowe (cs, en, …) i opcjonalnie podfolder files z obrazkami, które można wstawiać na strony dokumentacji.