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

Матеріал з Вікіпедії — вільної енциклопедії.
Перейти до: навігація, пошук
Скорочення
ВП:ДОК

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

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

Вміст документації[ред. код]

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

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

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

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

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

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

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

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

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

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

</includeonly>

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

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

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

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

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

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

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

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

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

Користь[ред. код]

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

Документація Templatedata[ред. код]

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

Приклади[ред. код]

Див. також[ред. код]



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