Pisanie dokumentacji

Tworzenie dokumentacji jest jednym z najbardziej satysfakcjonujących zajęć, ponieważ pomagasz innym zrozumieć framework.

Szybkie edycje

Najprostszym sposobem na edycję tekstu w dokumentacji jest użycie linków na dole 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 również zobaczyć wynikową 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 GitHuba po zakończeniu edycji. Poniżej pola edycyjnego znajduje się formularz do przesłania. Pamiętaj, aby krótko podsumować i wyjaśnić powód swojej edycji. Po wysłaniu zostanie utworzony pull request, który będzie można dalej edytować.

Jak pisać?

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

Pisząc, zacznij od tego, co proste i ogólne. Do bardziej zaawansowanych tematów przechodź na końcu.
Zawieraj tylko te informacje, które użytkownik naprawdę musi wiedzieć na dany temat.
Zweryfikuj, czy twoje informacje są rzeczywiście prawdziwe. Przetestuj najpierw kod, zanim go podasz.
Bądź zwięzły – zmniejsz to co piszesz o połowę. A potem zrób to jeszcze raz.
Postaraj się wyjaśnić sprawę najlepiej jak potrafisz. Na przykład, spróbuj najpierw wyjaśnić temat koledze.
Daruj sobie wszelkiego rodzaju zakreślacze, od pogrubionej czcionki po ramki np. .[note].

Pamiętaj o tych punktach podczas pisania. Zapoznaj się również z zasadami składni. Możesz użyć edytora pod glądu, aby wyświetlić podgląd artykułu w trakcie jego pisania.

Oprócz powyższych punktów, przestrzegaj również następujących wskazówek:

Angielski jest językiem podstawowym, więc Twoje zmiany powinny być w obu językach. Jeśli angielski nie jest twoją mocną stroną, użyj DeepL Translator, a inne osoby dokonają korekty twojego tekstu.
Postępuj zgodnie ze Standardem Kodowania w przykładach.
Pisz nazwy zmiennych, klas i metod w języku angielskim.
Przestrzenie nazw powinny być podawane przy pierwszej wzmiance.
Staraj się formatować swój kod tak, aby nie były wyświetlane paski przewijania.
W przypadku dokumentacji, odwołuj się tylko do dokumentacji lub www.

Wkład w dokumentację

Musisz mieć konto na GitHubie, aby wnieść wkład w dokumentację. Możesz wprowadzać proste zmiany bezpośrednio w jej interfejsie.

Jednak bardziej przydatna jest znajomość podstaw pracy z systemem wersjonowania Git. Jeśli nie jesteś zaznajomiony z Gitem, możesz sprawdzić ten szybki przewodnik: git – the simple guide, lub skorzystać z jednego z wielu narzędzi graficznych: GIT – klienci GUI.

Rozpocznij edycję dokumentacji tworząc fork repozytorium nette/docs i klonując go na swój komputer. Następnie dokonaj zmian w odpowiedniej gałęzi, popełnij zmianę, popchnij do swojego repozytorium na GitHubie i wyślij pull request do oryginalnego repozytorium nette/docs.

Przed każdym pull requestem warto uruchomić Code-Checker, aby sprawdzić, czy w tekście nie ma dodatkowych spacji.

Struktura dokumentacji

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

Zawartość każdej gałęzi jest podzielona na główne foldery reprezentujące każdy obszar 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 ewentualnie podfolder files z obrazkami, które można osadzić na stronach dokumentacji.