Википедија:Документирање на предлошки

Кратенки: ВП:ДОК

Предлошките се многу моќна алатка на МедијаВики, но во исто време збунувачки за новите корисници, па дури и поискусните корисници со потешкотии го разбираат значењето на посложените предлошки. Предлошките треба да бидат проследени со соодветна документација за да се објасни и зголеми нивната употреба.

Предложната документација треба да објасни зошто служи и како се користи предлошката. Треба да биде едноставна за да може и корисниците без некои пошироки познавања на синтаксата на предлошката, во кои спаѓаат и многу искусни уредувачи кои своето внимание го имаат фокусирано на друго место, да може правилно и успешно да го користат. Ова посебно е важно за предлошките кои се користат многу често.

Што да се вклучи во документацијата

Документацијата треба да го опфати следново:

Основната намена на предлошката: што прави, и (ако не е очигледно) зошто треба тоа да го направи. Ако постојат други предлошки со слично име или намена, добро би било истото да се наведе во документацијата, за да се намалат можностите за погрешно користење на некој од нив.
Параметрите на предлошката: објаснете дали се или нумерирани или именувани, без разлика дали се опционални (и ако е така, која би била општата, почетна вредност) и каков ефект тие имаат. Ако параметарот може да прима само одредени вредности (како „да“ и „не“, на пример), мора да биде број или е ограничен на било кој друг начин, сето тоа треба да се наведе.
Пример за употреба: прикажете го точниот викитекст кој треба да се користи и исходот од него. Викитекстот може да биде затворен со ознаките <code>...</code> за да биде видлив и лесен за копирање, како што е ова. Ако предлошката се користи на повеќе други начини (со или без опционалните параметри, на пример), обезбедете повеќе примери. Добар начин да се направи ова е да се превметнува самата предлошка во документацијата неколку пати, со различни параметри, и листа на искористените параметри користени во секој случај.
Поврзани предлошки: доколку предлошката е една од серија предлошки, вклучете врски до нив — особено, осигурајте се дека секоја предлошка во серијата е поврзана од една од друга, бидејќи тоа го олеснува прегледникот. (Одделна прегледничка предлошка може да биде корисна за оваа намена; за пример погледајте Предлошка:Предлошки за заштитување).
Категории кадешто се применливи. Како и документацијата, категориите мора да бидат содржани во ознаките <noinclude>...</noinclude>. Достапни се многу категории за предлошки, одете на Категорија:Предлошки за да ги прелистате.

Предложната документација често се сместува во потстраница на самата предлошка што потоа се превметнува на крајот од предложната страница. Ова го одделува често сложениот предложен код од документацијата, олеснувајќи го уредувањето на документацијата. Исто така, овозможува предлошките да бидат заштитени кадешто е потребно, а воедно му овозможува на секого да ја уредува документацијата. Овој метод понекогаш се нарекува „образец на страница со предложна документација“.

Документацијата од било кој вид на страница со предлошка секогаш треба да биде затворена со ознаки <noinclude>...</noinclude>, за да не се појавува кога предлошката се користи на друга страница. Текстот на самата страница со предлошка го зголемува количеството текст што мора да се обработи при прикажување на предлошката, што е ограничено од причини поврзани со перформансите. Ставањето на документацијата во потстраница го избегнува ова (програмерите на МедијаВики го препорачаа тоа поради оваа причина).

Како да создадете потстраница на документацијата

Потстраниците на документацијата треба да бидат именувани и форматирани според следниов општ образец, за конзистентност.

Да претпоставиме дека предлошката се именува Предлошка:X. Создајте потстраница со име Предлошка:X/doc. Употребете го следниов викитекст како почеток за документацијата:


<includeonly>{{template doc page transcluded}}</includeonly>

<!-- EDIT TEMPLATE DOCUMENTATION BELOW THIS LINE -->



<includeonly>

<!-- ADD CATEGORIES BELOW THIS LINE -->



<!-- ADD INTERWIKIS BELOW THIS LINE -->



</includeonly>

Во горниот ред ќе се прикаже една од двете предлошки — на врвот од документацијата; ова му става до знаење на читателот дека она што следи е документација и обезбедува врска за уредување на потстраницата /doc.

Вметнете ја документацијата и категориите како што е прикажано подолу во соодветните линии за коментари — оставајќи ги коментарите на место за да се зачува распоредот кога страницата ќе се уредува во иднина.

Зачувајте ја потстраницата и вратете се на предлошката, Предлошка:X во овој пример. Уредете ја предлошката и додадете го следново на крајот од кодот на предлошката:

[--template code--]<noinclude>
{{template doc}}

<!-- Add categories and interwikis to the /doc subpage, not here! -->

</noinclude>

Важно: Make sure the opening <noinclude> begins on the same line as the last character of the template code (or text), and not on a new line. Otherwise, extra space will be inserted below the template when it is used, which is usually not wanted.

If the template is already protected, ask an administrator to do this, or request an edit by using {{editprotected}} on the template's talk page. If documentation, categories and interwiki links already exist in a section enclosed with <nowiki> tags, move them into the documentation subpage, as it is best not to have documentation split across two separate pages.

Пример

See the heavily-used Предлошка:Наведена мрежна страница for an example of detailed template documentation. Note that the template itself is protected, but the documentation subpage, Предлошка:Наведена мрежна страница/doc is unprotected and can still be edited.

Поврзано