Pomoc:Schemat opisu szablonu

Niniejszy schemat opisu szablonu jest metodą bezpiecznego oddzielenia dokumentacji szablonu od kodu szablonu, poprzez umieszczenie dokumentacji na oddzielnej stronie. Pozwala to na całkowite zabezpieczenie szablonu, jednocześnie umożliwiając pozostawienie dokumentacji niezabezpieczonej, tak by wszyscy mogli ją edytować.

Co to daje?

Wikipedyści generalnie rzecz biorąc lubią, gdy instrukcja obsługi szablonu znajduje się na samej stronie szablonu (na przykład: [[Szablon:]]). Można to osiągnąć wpisując opis wprost do kodu szablonu wewnątrz tagów <noinclude>...</noinclude>. Powoduje to jednakże pewne problemy:

Tekst umieszczony w <noinclude>...</noinclude>dodaje się do pre-expand include size, który jest ograniczony (zobacz: Wikipedia:Ograniczenia szablonów).
Niektóre szablony są całkowicie zabezpieczone, ponieważ są dołączane do wielu stron. Edytowanie ich dokumentacji jest utrudnione, ponieważ nie-admini muszą prosić o pomoc administratora.
Istnieje górne ograniczenie zarówno rozmiaru strony przed dołączeniem szablonów jak i po [expand]. (...) (zobacz Wikipedia:Ograniczenia szablonów).

Ten How to opisuje strategię i sposób dokumentacji szablonów, który pozwala użytkownikom przypomnieć sobie zasady użycia szablonu (lub nauczyć się ich), a przy tym przyspiesza ładowanie stron i zmniejsza obciążenie serwerów.

Rozwiązaniem jest utworzenie dla dokumentacji i instrukcji obsługi szablonu dokumentacji i przechowywanie ich tam, zamiast wewnątrz samego szablonu narzędziowego. Szablon dokumentacji jest oddzielony od kodu blokiem noinclude—/noinclude, który jest bardzo krótki, a zatem łatwiejszy do przetworzenia przez procesor.

Daje to także dwa dodatkowe plusy:

Minimalizuje czas ładowania często używanych serwerów w przypadkach, gdy zmienione zostały w stopniu minimalnym, np. dodany został link interwiki.
Dokumentacja ważnych i zabezpieczonych szablonów może być rozszerzana i modyfikowana bez obawy o działanie samego szablonu.

Jak to się robi

Dla szablonu o nazwie Szablon:X, należy utworzyć stronę Szablon:X/opis i wkleić na nią następujący kod:


{{Podstrona dokumentacji}}

<!-- EDYTUJ DOKUMENTACJĘ SZABLONU PONIŻEJ TEJ LINII -->



<includeonly>

<!-- DODAJ KATEGORIE PONIŻEJ TEJ LINII -->



<!-- DODAJ INTERWIKI PONIŻEJ TEJ LINII -->

</includeonly>

Następnie wprowadź dokumentację, kategorie i interwiki w odpowiednie miejsca oznaczone komentarzami powyżej.

Na stronie szablonu X dodaj:


<noinclude>{{Dokumentacja}}

<!-- Kategorie i interwiki dodawaj do podstrony /opis, nie tutaj! -->

</noinclude>

Uwaga: Upewnij się, że otwierający znacznik <noinclude> znajduje się w tej samej linii co ostatni znak kodu (lub tekstu) szablonu, nie w nowej linii. W przeciwnym wypadku dodatkowa linia zostanie dodana do stron, do których dołączany jest X (co prawie nigdy nie jest pożądanym efektem).

Szablon może teraz być całkowicie zabezpieczony, a jego dokumentacja na 'X/opis' może pozostać niezabezpieczona, by każdy mógł ją edytować.

Plusy

Edycje strony X/opis wpływają tylko na wyświetlanie samej strony szablonu, nie na strony, do których X jest dołączony. A zatem strony te nie są zależne od strony opisu, więc edycje strony opisu nie powodują przyrostu job queue często używanych szablonów.
Edycje dokumentacji nie mogą uszkodzić szablonu ani stron, do których jest dołączony. Zwandalizowanie strony opisu nie przekłada się na strony, do których dołączony jest X.
Każdy może edytować dokumentację, nawet jeśli sam szablon jest zabezpieczony. Kategorie i interwiki mogą być z łatwością dodawane do podstrony X/opis.

Źródła

Tim Starling napisał: "If the documentation is large or frequently changed, I'd recommend that you move it to a subpage. Then you can transclude it into both the <noinclude> section and the talk page." [1]

Przykłady

Szablon:Szablon nawigacyjny uniwersalny (zabezpieczony), Szablon:Szablon nawigacyjny uniwersalny/opis (niezabezpieczony)