Wkład w dokumentację

Wkład w dokumentację jest jednym z najbardziej wartościowych działań, ponieważ pomaga innym zrozumieć framework.

Jak pisać?

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

• Zacznij od prostych i ogólnych tematów. Przejdź do bardziej zaawansowanych tematów na końcu
• Staraj się wyjaśnić temat tak jasno, jak to możliwe. Na przykład, spróbuj najpierw wytłumaczyć temat koledze.
• Podawaj tylko te informacje, które użytkownik rzeczywiście musi znać dla danego tematu
• Upewnij się, że informacje są dokładne. Testuj każdy kod
• Bądź zwięzły – skróć to, co piszesz o połowę. A potem nie krępuj się zrobić tego ponownie
• Oszczędnie używaj wyróżnień, od pogrubionych czcionek po ramki typu .[note]
• Stosuj się do Standardów Kodowania w kodzie

Ucz się również składni. Aby uzyskać podgląd artykułu podczas pisania, możesz użyć edytora podglądu.

Mutacje językowe

Angielski jest językiem podstawowym, więc twoje zmiany powinny być w języku angielskim. Jeśli angielski nie jest twoją mocną stroną, użyj DeepL Translator i inni sprawdzą twój tekst.

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

Trywialne edycje

Aby wnieść swój wkład w dokumentację, musisz mieć konto na GitHubie.

Najłatwiejszym sposobem na dokonanie niewielkiej zmiany w dokumentacji jest użycie linków na końcu każdej strony:

• Show on GitHub otwiera wersję źródłową strony na GitHubie. Następnie wystarczy nacisnąć przycisk E i można rozpocząć edycję (trzeba być zalogowanym na GitHubie)
• Open preview otwiera edytor, w którym można od razu zobaczyć ostateczną formę wizualną

Ponieważ edytor podglądu nie ma możliwości zapisywania zmian bezpośrednio na GitHubie, należy skopiować tekst źródłowy do schowka (za pomocą przycisku Copy to clipboard), a następnie wkleić go do edytora na GitHubie. Poniżej pola edycyjnego znajduje się formularz do przesłania. Tutaj nie zapomnij krótko podsumować i wyjaśnić powodu swojej edycji. Po przesłaniu tworzony jest tzw. pull request (PR), który można dalej edytować.

Większe edycje

Bardziej właściwe jest zapoznanie się z podstawami pracy z systemem kontroli wersji Git, niż poleganie wyłącznie na interfejsie GitHub. Jeśli nie jesteś zaznajomiony z Gitem, możesz zapoznać się z git – prostym przewodnikiem i rozważyć użycie jednego z wielu dostępnych klientów graficznych.

Edytuj dokumentację w następujący sposób:

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. sprawdzić, czy w tekście nie ma dodatkowych spacji za pomocą narzędzia Code-Checker
5. zapisz (commit) zmiany
6. jeśli jesteś zadowolony ze zmian, wepchnij je na GitHub do swojego forka
7. stamtąd prześlij je do repozytorium nette/docs tworząc pull request (PR)

Powszechne jest otrzymywanie komentarzy z sugestiami. Śledź proponowane zmiany i włączaj je. Dodaj sugerowane zmiany jako nowe commity i wyślij je ponownie do GitHub. Nigdy nie twórz nowego pull requesta tylko po to, by zmodyfikować istniejący.

Struktura dokumentacji

Cała dokumentacja znajduje się na GitHubie w repozytorium nette/docs. Aktualna wersja znajduje się w gałęzi master, natomiast starsze wersje znajdują się 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 mutacje językowe (cs, en, …) oraz opcjonalnie podfolder files z obrazkami, które można wstawić na strony w dokumentacji.