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

Матеріал з Wikiситет
Перейти до навігації Перейти до пошуку

Помилка скрипту: Не існує модуля «Message box».

Скорочення:
ВП:ДОК

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

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

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

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

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

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

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

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

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

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

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

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

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

</includeonly>

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

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

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

Шаблон:Колір фону<noinclude>

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

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

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

Якщо шаблон захищено, то запитайте дозволу у адміністратора або зробіть запит на редагування, використовуючи Шаблон:Tl2 на сторінці обговорення шаблона. Якщо в секції, оточеній контейнерами {{nowrap|<noinclude>…</noinclude>} вже існує документація, категорії та інтервікі, то перенесіть їх до підсторінки документації, оскільки краще, коли документація не розбита на дві окремі сторінки.

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

Користь

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

Приклади

Див. також


Вікіситет Це незавершена стаття.
Ви можете допомогти проекту, виправивши або дописавши її.