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.