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

Од Википедија — слободната енциклопедија
Прејди на: содржини, барај
Кратенки:
ВП:ДОК

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

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

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

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

  • Основната намена на шаблонот: што прави, и (ако не е очигледно) зошто треба тоа да го направи. Ако постојат други шаблони со слично име или намена, добро би било истото да се наведе во документацијата, за да се намалат можностите за погрешно користење на некој од нив.
  • Било кои параметри кои шаблонот ги прима, објаснете дали се или нумерирани или именувани, без разлика дали се опционални (и ако е така, која би била општата, почетна вредност) и каков ефект тие имаат. Ако параметарот може да прима само одредени вредности (како „да“ и „не“, на пример), мора да биде број или е ограничен на било кој друг начин, сето тоа треба да се наведе.
  • Пример за употреба. Прикажете го точниот викитекс кој треба да се користи и резултатот од него. Вики текстот може да биде затворен со <tt>...</tt> ознаките за да биде видлив и лесен за копирање, како што е ова. Ако шаблонот се користи на повеќе други начини (со или без опционалните параметри, на пример), обезбедете повеќе примери. Добар начин да се направи ова е да се трансклудира самиот шаблон во документацијата неколку пати, со различни параметри, и листа на искористените параметри користени во секој случај.
  • Поврзани шаблони. If the template is one of a series of templates, include links to these – in particular, ensure that every template in the series is linked from each of the others, as this makes navigation easier. (A separate navigation template may be useful for this purpose; see for example Template:Protection templates).
  • Соодветни категории и меѓујазични врски, where applicable. Like the documentation, these must be contained within <noinclude>...</noinclude> tags. Many template categories are available, go to Category:Wikipedia templates to browse through them.

Template documentation is often placed in a subpage of the template itself, which is then transcluded at the end of the template page. This separates the often complex template code from the documentation, making the documentation easier to edit. It also allows templates to be protected where necessary, while allowing anyone to edit the documentation. This method is sometimes referred to as the "template doc page pattern".

Documentation of any sort on a template page should always be enclosed by <noinclude>...</noinclude> tags, so that it does not show up when the template is used on another page. Text on the template page itself adds to the amount of text which must be processed when displaying the template, which is limited for performance reasons. Placing the documentation in a subpage avoids this (MediaWiki developers have recommended it for this reason).

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

Documentation subpages should be named and formatted using the following general pattern, for consistency.

Suppose your template is named Template:X. Create a subpage with the name Template:X/doc. Use the following wikitext as a start for the documentation:

<includeonly>{{template doc page transcluded}}</includeonly><noinclude>{{template doc page viewed directly}}</noinclude>
<!-- EDIT TEMPLATE DOCUMENTATION BELOW THIS LINE -->

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

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

</includeonly>

The top line will display one of two templates – {{template doc page transcluded}} or {{template doc page viewed directly}} – at the top of the documentation; this makes it clear to the reader that what followes is documentation, and provides a link to edit the /doc subpage.

Insert the documentation, categories and interwikis as below the appropriate comment lines – leaving the comments in place so that the layout is preserved when the page is edited in future.

Save the subpage, and return to the template itself, Template:X in this example. Edit the template and append the following at the end of the template code:

[--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 Template:Cite web for an example of detailed template documentation. Note that the template itself is protected, but the documentation subpage, Template:Cite web/doc is unprotected and can still be edited.

Поврзано[уреди]