Paweł Niemczuk: Utworzenie strony pomocy

2026-09-15T21:20:47Z

Utworzenie strony pomocy

Nowa strona

= Schemat opisu szablonu =

Niniejsza strona opisuje sposób tworzenia dokumentacji szablonów w Enkolu.

Dokumentacji rozbudowanego szablonu nie należy umieszczać bezpośrednio w jego kodzie. Zamiast tego należy utworzyć osobną podstronę dokumentacji o nazwie:

<pre>
Szablon:Nazwa szablonu/opis
</pre>

i dołączyć ją do strony właściwego szablonu.

Takie rozwiązanie oddziela kod wykonawczy szablonu od jego instrukcji obsługi. Ułatwia utrzymanie dokumentacji, zmniejsza ryzyko przypadkowego uszkodzenia szablonu podczas edycji opisu oraz pozwala niezależnie edytować kod i dokumentację.

== Schemat ==

Dla szablonu:

<pre>
Szablon:X
</pre>

tworzymy stronę:

<pre>
Szablon:X/opis
</pre>

Na stronie <code>Szablon:X</code> znajduje się właściwy kod szablonu, natomiast na stronie <code>Szablon:X/opis</code> jego dokumentacja.

== Tworzenie strony dokumentacji ==

Na początku strony:

<pre>
Szablon:X/opis
</pre>

należy umieścić:

<pre>
{{Podstrona dokumentacji}}
</pre>

Poniżej należy umieścić właściwą dokumentację szablonu.

Typowa dokumentacja może zawierać następujące sekcje:

<pre>
== Zastosowanie ==

== Użycie ==

== Parametry ==

== Przykłady ==

== Szablony podrzędne i pomocnicze ==

== Dane semantyczne ==

== Uwagi techniczne ==
</pre>

Nie każdy szablon wymaga wszystkich wymienionych sekcji. Dokumentacja powinna odpowiadać rzeczywistemu stopniowi złożoności szablonu.

== Dołączenie dokumentacji do szablonu ==

Na końcu właściwego kodu strony <code>Szablon:X</code> należy dodać:

<pre>
<noinclude>
{{Dokumentacja}}
</noinclude>
</pre>

'''Ważne:''' otwierający znacznik <code><noinclude></code> powinien znajdować się bezpośrednio po końcu kodu szablonu, w tej samej linii.

Przykład:

<pre>
</includeonly><noinclude>
{{Dokumentacja}}
</noinclude>
</pre>

Nie należy stosować:

<pre>
</includeonly>
<noinclude>
{{Dokumentacja}}
</noinclude>
</pre>

ponieważ znak końca linii pomiędzy właściwym kodem a <code><noinclude></code> może zostać uwzględniony przy dołączaniu szablonu do innych stron.

== Zalecana zawartość dokumentacji ==

=== Zastosowanie ===

Należy krótko opisać:
* do czego służy szablon;
* na jakiego rodzaju stronach powinien być używany;
* jakie informacje wyświetla lub generuje;
* czy zapisuje dane semantyczne.

Przykład:

<pre>
== Zastosowanie ==

Szablon służy do wyświetlania metryki pojazdu oraz zapisywania podstawowych danych jako właściwości Semantic MediaWiki.
</pre>

=== Użycie ===

Należy podać co najmniej jedno prawidłowe wywołanie szablonu.

Dla bardziej rozbudowanych szablonów wskazane jest podanie:
* przykładu minimalnego;
* przykładu pełnego lub typowego.

Przykład:

<pre>
== Użycie ==

<pre>
{{Nazwa szablonu
|Parametr1=
|Parametr2=
}}
</pre>
</pre>

Jeżeli dokumentowany kod zawiera znaczniki <code><pre></code>, można zamiast nich zastosować znaczniki <code><syntaxhighlight></code> albo odpowiednio rozdzielić przykłady, aby uniknąć zagnieżdżenia identycznych znaczników.

=== Parametry ===

Parametry najlepiej opisywać w tabeli:

<pre>
{| class="wikitable"
! Parametr
! Znaczenie
! Uwagi
|-
| <code>Parametr1</code>
| Opis parametru
| Informacja dodatkowa
|-
| <code>Parametr2</code>
| Opis parametru
| Pole opcjonalne
|}
</pre>

W opisie należy w szczególności zaznaczać:
* parametry obowiązkowe;
* parametry opcjonalne;
* wartości domyślne;
* dozwolone wartości;
* zależności między parametrami;
* szczególne zachowanie dla określonych wartości.

=== Przykłady ===

Jeżeli samo zestawienie parametrów nie wyjaśnia działania szablonu wystarczająco jasno, należy podać praktyczne przykłady.

Warto pokazywać przede wszystkim przypadki typowe oraz takie, w których zachowanie szablonu może nie być oczywiste.

=== Dane semantyczne ===

Jeżeli szablon korzysta z Semantic MediaWiki, dokumentacja powinna wskazywać zapisywane właściwości.

Przykładowy układ:

<pre>
{| class="wikitable"
! Właściwość
! Źródło danych
|-
| <code>Nazwa właściwości</code>
| parametr <code>Nazwa parametru</code>
|}
</pre>

Jeżeli właściwość jest zapisywana przez szablon podrzędny, warto również to zaznaczyć.

=== Szablony podrzędne i pomocnicze ===

W przypadku rozbudowanych szablonów należy wymienić szablony, od których zależy ich działanie.

Warto rozróżnić:

* '''szablony wywoływane bezpośrednio''' – znajdujące się w kodzie dokumentowanego szablonu;
* '''szablony pomocnicze''' – używane np. wewnątrz wartości jego parametrów albo przez inne szablony podrzędne.

Przykład:

<pre>
== Szablony podrzędne i pomocnicze ==

=== Szablony wywoływane bezpośrednio ===

* [[Szablon:X dane]] – wyświetla pojedynczy element danych;
* [[Szablon:X grafika]] – wyświetla grafikę.

=== Szablony pomocnicze ===

* [[Szablon:X historia]] – tworzy pojedynczy wpis historii.
</pre>

Dzięki temu łatwiej ustalić zależności pomiędzy szablonami przed ich zmianą albo usunięciem.

=== Uwagi techniczne ===

W tej sekcji można opisać informacje istotne dla osób utrzymujących kod, na przykład:
* sposób działania responsywnego układu;
* klasy CSS wykorzystywane przez szablon;
* zależność od <code>MediaWiki:Common.css</code>;
* sposób obsługi pustych parametrów;
* nietypowe zachowanie parsera;
* ograniczenia wynikające z konstrukcji szablonu.

Nie należy natomiast przepisywać tutaj całego kodu szablonu.

== Kategorie ==

Jeżeli szablon należy do kategorii, kategorię należy umieścić na jego podstronie dokumentacji, a nie bezpośrednio na stronie właściwego szablonu.

Na końcu strony <code>Szablon:X/opis</code> można w takim przypadku użyć:

<pre>
<includeonly>
[[Kategoria:Nazwa kategorii szablonów]]
</includeonly>
</pre>

Jeżeli szablon nie jest kategoryzowany, blok ten nie jest potrzebny.

== Dlaczego dokumentacja jest oddzielona od kodu ==

Oddzielenie dokumentacji od właściwego kodu daje kilka korzyści:

* dokumentację można edytować bez ingerowania w działający kod szablonu;
* zmiana opisu nie powoduje zmiany treści transkludowanej na stronach używających szablonu;
* rozbudowana instrukcja obsługi nie zwiększa niepotrzebnie kodu właściwego szablonu;
* łatwiej zabezpieczyć ważny szablon przed przypadkową zmianą, pozostawiając możliwość poprawiania jego dokumentacji;
* struktura stron szablonów jest bardziej przejrzysta.

== Przykład ==

Dla szablonu:

<pre>
Szablon:Lw metryka pojazdu
</pre>

dokumentacja znajduje się na stronie:

<pre>
Szablon:Lw metryka pojazdu/opis
</pre>

Końcówka właściwego szablonu ma postać:

<pre>
</includeonly><noinclude>
{{Dokumentacja}}
</noinclude>
</pre>

Natomiast strona dokumentacji rozpoczyna się od:

<pre>
{{Podstrona dokumentacji}}
</pre>

== Dobre praktyki ==

* Dokumentacja powinna opisywać aktualne działanie szablonu, a nie jego historyczne wersje.
* Po istotnej zmianie parametrów należy zaktualizować również stronę <code>/opis</code>.
* Nazwy parametrów w dokumentacji powinny być zapisane dokładnie tak samo jak w kodzie.
* W przykładach należy używać rzeczywiście obsługiwanych wartości.
* Nie należy dokumentować nieistniejących właściwości semantycznych ani nieużywanych podszablonów.
* Przed usunięciem szablonu podrzędnego należy sprawdzić jego użycie za pomocą strony „Linkujące tutaj”.
* Jeżeli zachowanie szablonu zależy od CSS, należy wskazać odpowiednie klasy lub stronę zawierającą style.
* Dokumentacja powinna być możliwie kompletna, ale nie powinna niepotrzebnie powtarzać oczywistych fragmentów kodu.

== Zobacz też ==

* [[Pomoc:Szablony]]
* [[MediaWiki:Common.css]]

== Źródło rozwiązania ==

Schemat oddzielania dokumentacji od kodu szablonu został opracowany na podstawie rozwiązania stosowanego w polskojęzycznej Wikipedii na stronie „Pomoc:Schemat opisu szablonu”.

Pomoc:Schemat opisu szablonu - Historia wersji

Paweł Niemczuk: Utworzenie strony pomocy