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

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

Документација шаблона треба да садржава објашњење шта шаблон ради и како га користити. Треба да буде једноставна у толикој мери да корисник који нема комплетну представу о замршености шаблонске синтаксе — што укључује велик број оних који доприносе Википедији већ дуже време и имају искуства али пажњу усмеравају негде друго (само на писање чланака, на пример) — може да употребљава шаблон исправно. Ово нарочито битно у случају шаблона који су широко коришћени.

Треба укључивати

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

• Основну сврху шаблона: шта представља и чини и ако није одмах очигледно, зашто то треба одрадити. Ако постоје други шаблони са сличним именима или сврхама, добро је поменути их, како би се смањила могућност коришћења погрешног.

• Параметре шаблона: да ли су нумерисани, именовани или опционални, и ако јесу, које су подразумеване вредности и какав ефекат имају. Ако параметар може узети само ограничен скуп вриједности или је на било који начин ограничен, на примјер, ако може користити само "да", "не" или број, то треба јасно објаснити.

• Примере коришћења: навести тачан Викитекст који може да буде коришћен и резултат који даје. Викитекст може бити обухваћен у <code>...</code> шаблону, како би био јасан и једноставан за копирање (попут једноставан за копирање ). Ако се шаблон може користити на неколико различитих начина, са или без изборних параметара, на пример, потребно је обезбедити низ више одређених примера. Добар начин да се то учини је да се сам узорак неколико пута унесе у документацију (тј.да се ​​користе конкретни примери), сваки пут са различитим параметрима и да се испишу параметри који се користе у сваком од тих случају. Са шаблоном:Шаблон:Xpd се ово може урадити без постављања шаблона двапут у Викитекст (врста олакшице).

• Сродне шаблоне: ако је шаблон један од низа шаблона, треба укључити линкове који воде ка њима - практично, осигурајте сваки шаблон у низу треба бити повезан са сваким другим, јер то олакшава навигацију у претрази. (Одвојени шаблон за навигацију може бити користан за ову сврху, можете погледати Шаблоне заштите).

• Категорије где је то могуће (Унутрашње Викимедија линкове који требају бити наведени на Википодатке). Као и документација, категорије морају бити наведене у <noinclude>...</noinclude> шаблону на шаблону или унутар <includeonly>...</includeonly> ознаке (ако се налазе на страници документације).

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

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

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

Подстраницу документације шаблона треба именовати и форматирати користећи општи образац за конзистентност. Претпоставимо да је ваш шаблон именован Шаблон:X. Погледати детаље на или покренути страницу копирањем следећег стандардног Викитекста:

{{Documentation subpage}}
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[</nowiki>[[Wikipedia:Wikidata]]<nowiki>]]) -->
== Usage ==


<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||
<!-- Categories below this line, please; interwikis at Wikidata -->

}}</includeonly>

У горњој линији ће се приказати порука која објашњава тренутну страницу и вези до странице шаблона.

Убацити документацију иза горње линије и категорије под одговарајућу линију коментара - оставите коментар на месту, тако да изглед буде сачуван када се страница уреди у будућности. Сродни шаблони, страница политике, пројекти, и сл. могу се повезати додавањем одјељка "Види такође".

Сачувати подстраницу и вратити се самом шаблону, Template:X у овом примеру. Уредити шаблон и додати следеће на крају кода шаблона

[--last line of your template code--]<noinclude>
{{Documentation}}
<!--Please add this template's categories to the /doc subpage, not here - thanks!-->
</noinclude>

Ово ће укључити {{documentation}} на дну странице шаблона.

Важно: Уверите се да отварање <noinclude> почиње одмах након последњег знака кода шаблона или текста, а не на новој линији, нити с било којим интервентним простором. У супротном, додатни простор ће бити уметнут испод шаблона када се користи, што обично није пожељно.

Ако је шаблон већ заштићен, затражите од администратора да то учини уместо вас или затражите измену помоћу {{edit protected}} на страници за разговор. Ако документација и категорије већ постоје у одељку, који се налази унутар шаблона <noinclude>...</noinclude>, преместите их у подстраницу документације (где би требало да се налазе у <includeonly>...</includeonly>), јер је најбоље да документација није подељена на две одвојене странице.

Ако се код прво стави на страницу шаблона, може се искористити могућност поновног учитавања да би се добио унапред попуњен скелет странице документа; ако страница документације још не постоји, кликом на линк за уређивање на страници шаблона учитат ћете садржај шаблона у пољу за уређивање.

Ако ипак желите да преусмерите страницу за разговор на то учините на док. подстраници на страну за разговор самог шаблона. Онда ће сви разговори који се односе на шаблон и његова документација завршити на истој страници. На пример, преусмери Template talk:X/docу Template talk:X.

Празан шаблон

Да бисте генерисали празан шаблон, који се затим може копирати из документације и залијепити на другу страницу, употријебите:

{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}

Примери

Да бисте генерисали параметар шаблона, попуњен сопственим именима својстава, користите:

({{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}

Категорије и унутрашњи линкови

• Да бисте поставили сам шаблон у категорију, додајте [[Category:Category name]] на подстраници документације.
• Да бисте креирали интервики везу за сам образац, идите на Википодатке и пратите упутства за додавање веза на странице.
• Да бисте подстраницу документације ставили у категорију, додајте код [[Category:Category name]]секције на подстраници документа.
• Да би шаблон поставио чланак у категорију (када чланак већ садржи шаблон), додајте [[Category:Category name]] на страници шаблона. Тачан положај унутар шифре шаблона може утицати на начин извршавања кода категорије.

/Страница песак и /тест случајева

Пре него што направите промене у шаблону, добро је да прво препишете код шаблона у страници песак, покренете тестове случајева, пошто би шаблон могао бити видљив на хиљадама или чак милионима страница. Ако креирате подстранице које се називају тачно /страница песак, /тест случајева у шаблон онда зелено поље {{documentation}}на шаблону аутоматски детектује ово и приказује везе до тих страница у заглављу.

Неколико шаблона, једна страница документације

When several templates work together or are very similar then it is often clearer and easier to maintain one single documentation page that documents them together. The simplest way to do this is to make a full documentation page at one of the templates, and then make "" from the other templates. See, for instance, {{wrap}}.

.Када неколико шаблона раде заједно или су веома слични онда је често јасније и лакше одржавати једну страницу са документацијом која их документује заједно. Најједноставнији начин да то урадите је да направите страницу са комплетном документацијом на неком од шаблона, а затим направите ботове браћаче из других шаблона. На пример,

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

Када се прикаже шаблон, он ће се повезати на страницу која може послужити као документација, онда је одвојена документација сувишна и не треба је креирати. На пример, стуб шаблона који ће, када се прикаже, повезати са Википедијом:Wikipedia:Stub. Ово је веома ретко, али некада може бити од помоћи.

Савети и трикови

Ево неколико савета за олакшавање писања документације

• Kansei 12 могу се уметнути писањем {{јапанске године|1800}}. Погледајте {{tlp|Japanese year|1800}} за сличне шаблоне.
• ХТМЛ ознаке као {{tag}}могу се лако уметнути са <tag>...</tag>. Овај пример је написан као <ref group="note">...</ref>
• Знак једнакости = може бити унесен кодом {{=}} На пример, је направљен од странице {{tlp|Citation needed|date{{=}}07. 2019.}}. Избегавајте еквивалентну нотацију & # 61; јер другим уредницима неће бити лако читати.
• Не заборавите ознаку [[<nowiki />example]] постаје [[пример]], и [<nowiki />http://sr.wikipedia.org без линка]
• За везу до категорије користите [[:Категорија:{{{1}}}]]. На пример, {{cat}} постаје категорија: шаблони са нетачном синтаксом параметара.
• Да бисте сузбили категоризацију страница /страница песак и /тест случајева шаблона (ако постоје), користите овај код при дну подстранице документације. Линкови на шаблоне:

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||{{#ifeq:{{SUBPAGENAME}}|testcases||
<!--Categories below here, please; interwikis to Wikidata.-->

}}}}</includeonly>

Види још

• {{Documentation}} — Преведена је документација на страници шаблона, и пружа преглед документације, уређивање и повезивање историје
• {{Documentation subpage}} — Објашњава да оно што следи је документација и линкови на документовану страницу
• <noinclude> and <includeonly>
• {{Improve documentation}}
• {{No documentation}}
• {{Template reference list}}
• Wikipedia:High-risk templates
• Wikipedia:Template sandbox and test cases