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.