Вікіпедія:Документація шаблонів
Помилка скрипту: Не існує модуля «Message box».
Шаблони — дуже потужний інструмент MediaWiki, але вони можуть збити з пантелику нових користувачів. Навіть досвідчені користувачі можуть зазнавати труднощів в розумінні деяких складних випадків. Тому шаблони повинні супроводжуватися документацією для підвищення простоти використання.
Документація шаблону повинна пояснити призначення шаблону і особливості його використовувати. Вона повинна бути досить простою, щоб користувач без повного знання тонкощів синтаксису шаблонів — включаючи багатьох досвідчених учасників проекту, які могли б застосувати свої знання в інших місцях — міг правильно його використовувати. Особливо це стосується шаблонів, які часто використовуються.
Вміст документації
Документація шаблону повинна охоплювати:
- Основну мету шаблону: що він робить, і якщо це не очевидно, для чого його слід використовувати. Особливо це актуально у випадку, коли є інші шаблони зі схожими назвами або призначенням.
- Параметри шаблону: чи є вони нумеровані, іменовані, а також чи є вони необов'язковим, і якщо так, то яке в них значення за замовчуванням, і який ефект воно дає. Якщо параметр може приймати лише обмежений набір значень або значення обмежені яким-небудь іншим чином, наприклад, якщо значенням параметру може бути лише «так», «ні» або яке-небудь число, то це має бути чітко роз'яснено.
- Приклади використання: вказати точний вікітекст, який повинен бути використаний і результат використання шаблону. Вікітекст може бути укладений у контейнер
<code>…</code>, щоб зробити його чітким для сприйняття і легким для копіювання. Якщо шаблон може бути використаний в декількох варіантах, наприклад, з додатковими параметрами або без них, надають декілька прикладів.
- Пов'язані шаблони: якщо шаблон є одним із серії шаблонів, в документацію включають посилання на них, зокрема для того, щоб гарантувати зв'язок кожного шаблону з іншими з цієї серії, і таким чином зробити навігацію простішою.
- Категорії та інтервікі-посилання, там, де це доречно. Подібно до документації, вони повинні бути в межах контейнеру
<noinclude>…</noinclude>. Доступні багато категорій шаблонів, переглянути які можна використовуючи сторінку Категорія:Шаблони.
Документація шаблону часто вкладається у підсторінку самого шаблону, яка потім вставляється в кінці сторінки шаблону. Це відокремлює код складного шаблону від його документації, що в свою чергу спрощує редагування самої документації. Це також дозволяє в разі потреби захистити код шаблону не забороняючи при цьому редагування його документації.
Документація будь-якого виду завжди повинна бути вкладена у контейнер <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.
- Будь-хто може редагувати документацію, додавати категорії та інтервікі, навіть якщо шаблон захищений.
Приклади
- Шаблон:cite web (захищена), Шаблон:Cite web/документація (незахищена)
Див. також
|
Це незавершена стаття. Ви можете допомогти проекту, виправивши або дописавши її. |