Перегляд вихідного коду сторінки Вікіпедія:Документація шаблонів

{{translate}}
{{Ярлик|ВП:ДОК}}
[[Довідка:Шаблони|Шаблони]] — дуже потужний інструмент [[MediaWiki]], але вони можуть збити з пантелику нових користувачів. Навіть досвідчені користувачі можуть зазнавати труднощів в розумінні деяких складних випадків. Тому шаблони повинні супроводжуватися '''[[Документація|документацією]]''' для підвищення простоти використання.

Документація шаблону повинна пояснити призначення шаблону і особливості його використовувати. Вона повинна бути досить простою, щоб користувач без повного знання тонкощів синтаксису шаблонів — включаючи багатьох досвідчених учасників проекту, які могли б застосувати свої знання в інших місцях — міг правильно його використовувати. Особливо це стосується шаблонів, які часто використовуються.

== Вміст документації ==

Документація шаблону повинна охоплювати:

* Основну '''мету шаблону''': що він робить, і якщо це не очевидно, для чого його слід використовувати. Особливо це актуально у випадку, коли є інші шаблони зі схожими назвами або призначенням.

* '''[[Довідка:Шаблони#|Параметри]]''' шаблону: чи є вони нумеровані, іменовані, а також чи є вони необов'язковим, і якщо так, то яке в них значення за замовчуванням, і який ефект воно дає. Якщо параметр може приймати лише обмежений набір значень або значення обмежені яким-небудь іншим чином, наприклад, якщо значенням параметру може бути лише «так», «ні» або яке-небудь число, то це має бути чітко роз'яснено.

* '''Приклади використання''': вказати точний вікітекст, який повинен бути використаний і результат використання шаблону. Вікітекст може бути укладений у контейнер {{nowrap|<code><nowiki><code>…</code></nowiki></code>}}, щоб зробити його чітким для сприйняття і легким для копіювання. Якщо шаблон може бути використаний в декількох варіантах, наприклад, з додатковими параметрами або без них, надають декілька прикладів.

* '''Пов'язані шаблони''': якщо шаблон є одним із серії шаблонів, в документацію включають посилання на них, зокрема для того, щоб гарантувати зв'язок кожного шаблону з іншими з цієї серії, і таким чином зробити навігацію простішою.

* '''[[Вікіпедія:Категоризація|Категорії]]''' та '''[[Довідка:Інтервікі|інтервікі-посилання]]''', там, де це доречно. Подібно до документації, вони повинні бути в межах контейнеру {{nowrap|<code><nowiki><noinclude>…</noinclude></nowiki></code>}}. Доступні багато категорій шаблонів, переглянути які можна використовуючи сторінку [[:Категорія:Шаблони]].

Документація шаблону часто вкладається у [[Вікіпедія:Підсторінки|підсторінку]] самого шаблону, яка потім вставляється в кінці сторінки шаблону. Це відокремлює код складного шаблону від його документації, що в свою чергу спрощує редагування самої документації. Це також дозволяє в разі потреби [[Вікіпедія:Правила захисту сторінок|захистити]] код шаблону не забороняючи при цьому редагування його документації.

Документація будь-якого виду завжди повинна бути вкладена у контейнер {{nowrap|<code><nowiki>&lt;noinclude>…&lt;/noinclude></nowiki></code>}} на сторінці шаблону, і таким чином не з'являтиметься на сторінці де використовується такий шаблон. Будь-який текст на сторінці шаблону збільшує об'єм коду, який обробляється при відображенні шаблону, і на який накладені певні [[:en:Wikipedia:Template limits|обмеження]] для забезпечення продуктивності роботи MediaWiki. Розміщення документації на підсторінці дозволяє уникнути цього і це рекомендовано розробниками MediaWiki.

== Створення підсторінки документації ==

Підсторінка документації шаблону повинна бути названа і відформатована з використанням наступних загальних правил.

Нехай ваш шаблон називається <code>Шаблон:X</code>. Тоді необхідно створити підсторінку з ім’ям <code>Шаблон:X/документація</code>. Щоб дізнатись більше слід переглянути сторінку {{tl|Підсторінка документації}} або просто використати наступний вікітекст як початок для документації:

<pre>
{{Підсторінка документації}}
<!-- РЕДАГУЙТЕ ДОКУМЕНТАЦІЮ ШАБЛОНУ НИЖЧЕ ЦЬОГО РЯДКА -->

==Використання==

<includeonly>
<!-- ДОДАВАЙТЕ КАТЕГОРІЇ НИЖЧЕ ЦЬОГО РЯДКА, ІНТЕРВІКІ ДОДАВАЙТЕ НА ВІКІДАНИХ -->

</includeonly>
</pre>

Верхній рядок виводить повідомлення, що пояснює призначення цієї сторінки і містить посилання на сторінку шаблону.

Текст документації, а також категорії та інтервікі слід вставляти під відповідним рядком коментаря, залишивши сам коментар на місці, для можливих майбутніх редагувань. Шаблон підсторінки документації містить <nowiki>{{DEFAULTSORT:{{PAGENAME}}}}</nowiki>, забезпечуючи правильне сортування сторінки <code>Шаблон:X</code> під літерою «X», а не «Ш», таким чином, не бажано додавати до категорій змінну {{PAGENAME}} як ключ сортування.

Зберігши підсторінку документації слід повернутися до самого шаблону, в нашому прикладі до сторінки <code>Шаблон:X</code> і відредагувати його додавши в кінці коду шаблону наступний текст:

 {{Колір фону|#CCC|''[--останній рядок коду вашого шаблону--]''}}<nowiki><noinclude>

{{Документація}}
<!-- ДОДАВАЙТЕ КАТЕГОРІЇ ТА ІНТЕРВІКІ ШАБЛОНУ НА ПІДСТОРІНКУ ДОКУМЕНТАЦІЇ, А НЕ ТУТ! -->
</noinclude></nowiki>

Таким чином {{tl|Документація}} буде під’єднана до кінця сторіки шаблону.

'''Важливо''': Переконайтеся в тому, що <code><nowiki><noinclude></nowiki></code> починається в одному рядку з останнім символом коду шаблону, а ''не'' в новому рядку. В іншому випадку при використанні шаблону під ним буде вставлений додатковий відступ, який як правило є небажаним.

Якщо шаблон захищено, то запитайте дозволу у [[Вікіпедія:Адміністратори|адміністратора]] або зробіть запит на редагування, використовуючи {{tl2|Editprotected}} на сторінці обговорення шаблона. Якщо в секції, оточеній контейнерами {{nowrap|<code><nowiki>&lt;noinclude>…&lt;/noinclude></nowiki></code>} вже існує документація, категорії та інтервікі, то перенесіть їх до підсторінки документації, оскільки краще, коли документація не розбита на дві окремі сторінки.

Ви можете зробити перенаправлення підсторінки /doc на сторінку обговорення самого шаблону. Тоді всі обговорення, що стосуються шаблона та його документації будуть в кінці тої ж самої сторінки обговорення. Наприклад, перенаправлення <code>Template talk:X/doc</code> на <code>Template talk:X</code>.

== Користь ==
* Редагування на сторінці документації поширюються лише на сторінку шаблону, а не на всі включення сторінки X. Сторінки що включають X не залежать від сторінки документації, тому не завантажують [[mw:Manual:Job queue|job queue]].
* Редагування документації не шкодять шаблону. Вандалізм на сторінках документації не поширюється на сторінки що використовують X.
* Будь-хто може редагувати документацію, додавати категорії та інтервікі, навіть якщо шаблон захищений.

== Приклади ==
* [[Шаблон:cite web]] (захищена), [[Шаблон:Cite web/документація]] (незахищена)

== Див. також ==
* [[m:Help:Templates#Noinclude_and_includeonly|&lt;noinclude> and &lt;includeonly>]]
* [[Wikipedia:High-risk templates]]
* [[Шаблон:Підсторінка документації]]

{{Wiki-stub}}
{{DEFAULTSORT:{{PAGENAME}}}}

[[Категорія:Вікіпедія:Довідка|Шаблон]]
[[Категорія:Документації шаблонів| ]]