Вікіпедія:Документація шаблонів
Ця сторінка — довідка, призначена для подання опису певних аспектів вікіпедійних норм, звичаїв, практик. Вона може відображати різні рівні консенсусу, але це не політика і не настанова. |
Базові принципи, наведені на сторінці, стосуються також документації модулів Вікіпедії. |
Шаблони Вікіпедії — дуже потужний інструмент MediaWiki, але вони можуть збити з пантелику нових користувачів. Навіть досвідчені користувачі можуть зазнавати труднощів у розумінні деяких складних випадків. Тому шаблони повинні супроводжуватися документацією для підвищення розуміння їхнього використання.
Документація шаблону повинна пояснити призначення шаблону і особливості його використання. Вона повинна бути досить простою, щоб користувач без повного знання тонкощів синтаксису шаблонів — включаючи багатьох досвідчених учасників проєкту, які могли б застосувати свої знання в інших місцях — міг правильно ним скористатися. Особливо це стосується часто уживаних шаблонів.
Вміст документації
ред.Документація шаблону повинна охоплювати:
- Основну мету шаблону: для чого призначений, де використовується, що він робить, і якщо це не очевидно, у яких випадках його слід використовувати. Особливо це актуально у разі, коли існують інші шаблони зі схожими назвами чи призначенням.
- Параметри шаблону: чи є вони нумеровані, іменовані, а також чи є вони необов'язковими, і якщо так, то яке в них значення за замовчуванням, і який ефект воно дає. Якщо параметр може приймати лише обмежений набір значень, або значення обмежені яким-небудь іншим чином, наприклад, якщо значенням параметру може бути лише «так», «ні» або яке-небудь число, то це має бути чітко роз'яснено.
- Приклади використання: вказати точний вікітекст, який повинен бути використаний і результат використання шаблону. Вікітекст може бути укладений у контейнер
<code>…</code>
, щоб зробити його чітким для сприйняття і легким для копіювання. Якщо шаблон може бути використаний в декількох варіантах, наприклад, з додатковими параметрами або без них, надають декілька прикладів.
- Пов'язані шаблони: якщо шаблон є одним із серії шаблонів, в документацію включають посилання на них, зокрема для того, щоб гарантувати зв'язок кожного шаблону з іншими з цієї серії, і таким чином зробити навігацію простішою.
- Категорії та інтервікі-посилання, там, де це доречно. Подібно до документації, вони повинні бути прописані в межах контейнеру
<noinclude>…</noinclude>
. Доступні багато категорій шаблонів, переглянути які можна використовуючи сторінку Категорія:Шаблони.
Документація шаблону часто вкладається у підсторінку шаблону, посилання на таку підсторінку потім вставляється в кінці сторінки шаблону. Це відокремлює код складного шаблону від його документації, що, зі свого боку, спрощує редагування самої документації. Це також дозволяє в разі потреби захистити код шаблону, не забороняючи при цьому редагування його документації.
Документація будь-якого виду завжди повинна бути вкладена в контейнер <noinclude>…</noinclude>
на сторінці шаблону, і, таким чином, не з'являтиметься на сторінці, де використовується такий шаблон. Будь-який текст на сторінці шаблону збільшує розмір коду, який обробляється при відображенні шаблону, і на який накладені певні обмеження для забезпечення продуктивності роботи MediaWiki. Розміщення документації на підсторінці дозволяє уникнути цього, тому це рекомендовано розробниками MediaWiki.
Створення підсторінки документації
ред.Підсторінка документації шаблону повинна бути названа і відформатована з використанням наступних загальних правил.
Нехай створюваний вами шаблон називається Шаблон:X
. Тоді необхідно створити підсторінку з ім'ям Шаблон:X/документація
(слово документація має бути українською, з малої літери[1]). Аби дізнатися більше, слід переглянути сторінку {{Підсторінка документації}} або просто використати наступний вікітекст як початок для документації:
{{Підсторінка документації}} <!-- РЕДАГУЙТЕ ДОКУМЕНТАЦІЮ ШАБЛОНУ НИЖЧЕ ЦЬОГО РЯДКА --> == Використання == <includeonly> <!-- ДОДАВАЙТЕ КАТЕГОРІЇ НИЖЧЕ ЦЬОГО РЯДКА, ІНТЕРВІКІ ДОДАВАЙТЕ НА ВІКІДАНИХ --> </includeonly>
Верхній рядок виводить повідомлення, яке пояснює призначення цієї сторінки і містить посилання на сторінку шаблону.
Текст документації, а також категорії та інтервікі слід вставляти під відповідним рядком коментаря, залишивши сам коментар на місці, для можливих майбутніх редагувань. Шаблон підсторінки документації містить {{DEFAULTSORT:{{PAGENAME}}}}, забезпечуючи правильне сортування сторінки Шаблон:X
під літерою «X», а не «Ш»; таким чином, не бажано додавати до категорій змінну Документація шаблонів як ключ сортування.
Зберігши підсторінку документації, слід повернутися до самого шаблону, у цьому прикладі — до сторінки Шаблон:X
, і відредагувати його, додавши в кінці коду шаблону наступний текст:
[--останній рядок коду вашого шаблону--]<noinclude>
{{Документація}}
<!-- ДОДАВАЙТЕ КАТЕГОРІЇ ШАБЛОНУ НА ПІДСТОРІНКУ ДОКУМЕНТАЦІЇ, А НЕ ТУТ! -->
</noinclude>
Таким чином, {{Документація}} буде включена в кінець сторінки шаблону.
Важливо: Переконайтеся в тому, що <noinclude>
починається в одному рядку з останнім символом коду шаблону, а не в новому рядку. В іншому разі при використанні шаблону під ним буде вставлений додатковий відступ, який зазвичай не є бажаним.
Якщо шаблон захищений, то запитайте дозволу у адміністратора або зробіть запит на редагування, використовуючи {{Editprotected}} на сторінці обговорення шаблону. Якщо в секції, оточеній контейнерами <noinclude>…</noinclude>
вже існує документація, категорії та інтервікі, то перенесіть їх до підсторінки документації, оскільки краще, коли документація не розбита на дві окремі сторінки.
Ви можете зробити перенаправлення підсторінки /документація на сторінку обговорення самого шаблону. Тоді всі обговорення, що стосуються шаблону та його документації будуть у кінці тої ж самої сторінки обговорення. Наприклад, перенаправлення Обговорення шаблону:X/документація
на Обговорення шаблону:X
.
- Користь
- Редагування на сторінці документації поширюються лише на сторінку шаблону, а не на всі включення сторінки X. Сторінки, які включають X, не залежать від сторінки документації, тому не завантажують job queue.
- Редагування документації не шкодять шаблону. Вандалізм на сторінках документації не поширюється на сторінки, які використовують X.
- Будь-хто може редагувати документацію, додавати категорії, навіть якщо шаблон захищений.
Інлайн-документація
ред.У разі, якщо документація шаблону складається з невеликої кількості рядків, альтернативою створення окремої підсторінки документації є інлайн-документація — тобто коли документація шаблону прописана безпосередньо на сторінці шаблону, а не на окремій підсторінці.
Існує два способи інлайн-документації:
- За допомоги параметру
|content=
шаблону {{Документація}}. Цей варіант не підтримує вертикальні риски. - За допомоги пари шаблонів {{doc-begin}} та {{doc-end}}.
Інлайн-документація не має містити лише категорії та інтервікі!
TemplateData
ред.Механізм TemplateData розроблено для застосування шаблонів у візуальному редакторі Вікіпедії. Він документує окремі параметри шаблону, зокрема, дозволяє задати назву параметра різними мовами, короткий опис, навести приклад застосування, визначити формат даних та правила автоматичного заповнення, встановити обов'язкові для заповнення параметри чи позначити застарілі (залишені для сумісності) тощо.
Приклади
ред.- Шаблон:Cite web (захищена), Шаблон:Cite web/документація (незахищена)