Вікіпедія:Документація шаблонів

Шаблони — дуже потужний інструмент MediaWiki, але вони можуть збити з пантелику нових користувачів. Навіть досвідчені користувачі можуть зазнавати труднощів в розумінні деяких складних випадків. Тому шаблони повинні супроводжуватися документацією для підвищення простоти використання.

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

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

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

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

• Параметри шаблону: чи є вони нумеровані, іменовані, а також чи є вони необов’язковим, і якщо так, то яке в них значення за замовчуванням, і який ефект воно дає. Якщо параметр може приймати лише обмежений набір значень або значення обмежені яким-небудь іншим чином, наприклад, якщо значенням параметру може бути лише «так», «ні» або яке-небудь число, то це має бути чітко роз’яснено.

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

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

• Категорії та посилання InterWikimedia, там де це доречно. Подібно до документації, вони повинні бути в межах контейнеру <noinclude>…</noinclude>. Доступні багато категорій шаблонів, переглянути які можна використовуючи сторінку .

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

Документація будь-якого виду завжди повинна бути вкладена у контейнер <noinclude>…</noinclude> на сторінці шаблону, і таким чином не з’являтиметься на сторінці де використовується такий шаблон. Будь-який текст на сторінці шаблону збільшує об’єм коду, який обробляється при відображенні шаблону, і на який накладені певні обмеження для забезпечення продуктивності роботи MediaWiki. Розміщення документації на підсторінці дозволяє уникнути цього і це рекомендовано розробниками MediaWiki.

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

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

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

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

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

<includeonly>
<!-- ДОДАВАЙТЕ КАТЕГОРІЇ ПІД ЦИМ РЯДКОМ -->

<!-- ДОДАВАЙТЕ ІНТЕРВІКІ ПІД ЦИМ РЯДКОМ -->

</includeonly>

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

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

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

[--останній рядок коду вашого шаблону--]<noinclude>

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

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

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

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

If the code is put on the template page first, one can benefit from the preload feature to get a pre-filled doc page skeleton; if the documentation page does not exist yet, clicking the edit link on the template page will preload the contents of Template:Documentation/preload into the editbox of the /doc subpage creation.

You may wish to redirect the talk page of the /doc subpage to the talk page of the template itself. Then all talk relating to the template and its documentation will end up on the same talkpage. For example, redirect Template talk:X/doc to Template talk:X.

Користь

• Редагування на сторінці документації поширюються лише на сторінку шаблону, а не на всі включення сторінки X. Сторінки що включають X не залежать від сторінки документації, тому не завантажують job queue.
• Редагування документації не шкодять шаблону. Вандалізм на сторінках документації не поширюється на сторінки що використовують X.
• Будь-хто може редагувати документацію, додавати категорії та інтервікі, навіть якщо шаблон захищений.

Приклади

• Шаблон:cite web (захищена), Шаблон:Cite web/Документація (незахищена)

Дивіться також

• <noinclude> and <includeonly>
• Wikipedia:High-risk templates
• Шаблон:Підсторінка документації