Шаблоны — очень мощная функция MediaWiki , но они могут сбивать с толку новых пользователей, и даже опытные пользователи могут испытывать трудности с пониманием более сложных шаблонов. Поэтому шаблоны должны сопровождаться документацией для повышения удобства использования.
Документация шаблона должна объяснять, что делает шаблон и как его использовать. Она должна быть достаточно простой, чтобы пользователь без полного знания тонкостей синтаксиса шаблона (включая многих опытных участников, которые сосредоточили свое внимание на чем-то другом) мог использовать ее правильно. Это особенно верно в случае очень широко используемых шаблонов.
Редакторы должны полагаться на официальные политики или руководства , когда страницы документации шаблонов не соответствуют установленным стандартам и принципам сообщества. Редакторы также должны избегать «цитирования» страниц документации шаблонов, как будто они являются политикой, включая это руководство . Страницы документации шаблонов могут быть написаны без особых — если таковые вообще будут — дебатов, в отличие от политик Википедии, которые были тщательно проверены сообществом (см. WP: Local consensus для получения подробной информации).
Шаблонная документация должна охватывать:
<code>...</code>контейнер, чтобы сделать его понятным и easy to copy, like this. Если шаблон можно использовать несколькими способами, например, с дополнительными параметрами или без них, предоставьте ряд примеров. Хороший способ сделать это — несколько раз включить сам шаблон в документацию (т. е. использовать живые примеры) с разными параметрами каждый раз и перечислить параметры, используемые в каждом случае. С помощью {{ demo }} это можно сделать без помещения вызова шаблона дважды в викитекст.<noinclude>...</noinclude>контейнере в шаблоне или в<includeonly>{{Sandbox other||...}}</includeonly>тегах, если они размещены на странице документации. Доступно множество категорий шаблонов, см.: Категория:Шаблоны Wikipedia , чтобы просмотреть их.Английская Википедия является источником шаблонов для сотен других Википедий и родственных проектов. Часто шаблоны полностью самодостаточны, поэтому процесс прост: содержимое просто копируется на новую страницу шаблона в другой вики, и все работает. Однако в более сложных шаблонах шаблон может вызывать модуль, включать другие шаблоны, работать только в паре с отдельным шаблоном или требовать для работы определенный код CSS или JavaScript. В этих случаях полезно включить краткий список шаблонов или другой код, который требуется этому, в конце документации.
При просмотре самой страницы шаблона (в отличие от ее викикода) обычно сразу под заголовком отображается сам шаблон, за которым следует отдельный раздел для отображения документации шаблона, а затем категории, к которым принадлежит шаблон. Категории и документация любого рода на странице шаблона (включая TemplateData ) всегда должны быть заключены в теги noinclude , чтобы они не отображались при использовании шаблона на другой странице.
Редактируемый викикод для документации шаблона часто размещается на отдельной подстранице самого шаблона, которая затем транслируется в конец страницы шаблона. Это отделяет часто сложный код шаблона от документации, что упрощает редактирование документации и сокращает количество случайных ошибок редактирования в коде шаблона. Это также позволяет защищать шаблоны, где это необходимо, ограничивая доступ к редактированию важного кода шаблонов, в то же время позволяя любому редактировать документацию этих шаблонов. Этот метод иногда называют «шаблоном страницы шаблон-документ».
При создании (публикации) шаблона необходимо указать {{ documentation }} . Затем создается страница документации со [view] [edit] [history] [purge]ссылками. Вы можете создавать и редактировать документацию шаблона, нажав на [edit]ссылку в этой панели.
Подстраницы документации шаблонов, использующие {{ documentation }}, именуются и форматируются с использованием следующего общего шаблона для обеспечения единообразия.
Предположим, ваш шаблон называется Template:X. Отредактируйте шаблон и добавьте следующее в конец кода шаблона или используйте {{subst: doc-code }}:
[--последняя строка кода вашего шаблона--] <noinclude>{{Документация}}<!-- Добавляйте категории на подстраницу /doc и в интервики в Викиданных, а не здесь! --></noinclude>Это позволит включить {{ documentation }} в нижнюю часть страницы шаблона.
Важно : Убедитесь, что открытие <noinclude>начинается сразу после последнего символа кода шаблона или текста, а не на новой строке и не с пробелами. В противном случае, при использовании шаблона под ним будет вставлен дополнительный пробел, что обычно нежелательно.
Если шаблон уже защищен, попросите администратора сделать это или запросите редактирование, используя на странице обсуждения шаблона. Если документация и категории уже существуют в разделе, заключенном в контейнер, переместите их на подстраницу документации (где они должны быть заключены в ), так как лучше не разделять документацию на две отдельные страницы.{{edit protected}}<noinclude>...</noinclude><includeonly>...</includeonly>
Используйте [create]ссылку внизу пустого поля документации, чтобы автоматически создать предварительно загруженную подстраницу документации. Вставьте документацию после верхней строки и категории под соответствующей строкой комментария – оставив комментарий на месте, чтобы сохранить макет при редактировании страницы в будущем. Связанные шаблоны, страницу политики, проекты и т. д. можно связать, добавив раздел «См. также». Сохраните подстраницу.
Чтобы создать подстраницу документации вручную, создайте подстраницу с именем Template:X/doc. Подробности см. на {{ Documentation subpage }} или начните страницу, скопировав и вставив следующий стандартный викитекст:
{{ Подстраница документации }} == Использование ==< includeonly >{{ Песочница другое || <!-- Категории ниже этой строки -->}}</ включить только >В верхней строке отобразится сообщение, поясняющее текущую страницу, и ссылка на страницу шаблона. Сохраните подстраницу и следуйте инструкциям в разделе «Использование шаблона:Документация».
Вместо того, чтобы вручную писать лид-граф и таблицу использования, шаблон {{ Format TemplateData }} может выполнить большую часть работы. Просто напишите свой TemplateData в интерфейсе таблицы, а затем оберните его в вызов шаблона, как {{Format TemplateData|1=<templatedata>...</templatedata>}}в верхней части страницы.
Вы можете перенаправить страницу обсуждения подстраницы /doc на страницу обсуждения самого шаблона. Тогда все обсуждения, касающиеся шаблона и его документации, будут попадать на одну и ту же страницу обсуждения. Например, перенаправьте Template talk:X/docна Template talk:X.
Страница документации также может быть перенаправлена на подстраницу /doc другого шаблона, если это охватывает использование для обоих шаблонов. В этом случае нажатие ссылок для просмотра или редактирования документации напрямую откроет цель перенаправления. Если необходимо получить доступ к самому перенаправлению (например, чтобы удалить перенаправление и создать отдельную страницу документа), перейдите по URL шаблона, щелкнув в адресной строке в верхней части браузера, и добавьте /doc в конце.
Чтобы создать пустой шаблон, который затем можно скопировать из документации и вставить на другую страницу, используйте:
{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}Чтобы создать экземпляр шаблона, заполненный собственными именами свойств, используйте:
{{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}[[Category:Category name]]код внутри <includeonly>...</includeonly>раздела на подстранице документа . Смотрите Wikipedia:Categorization § Template categorization для рекомендаций.[[Category:Category name]]код внутри <noinclude>...</noinclude>раздела на подстранице документа .[[Category:Category name]]код в <includeonly>...</includeonly>раздел на странице шаблона. Точное размещение в коде шаблона может повлиять на то, как выполняется код категории. См. Wikipedia:Categorization § Categorization using templates для рекомендаций.Перед внесением изменений в шаблон может быть полезно сначала скопировать код шаблона в песочницу и запустить несколько тестовых случаев, поскольку шаблон может быть виден на тысячах или даже миллионах страниц. Если вы создаете подстраницы с именами " /sandbox " и " /testcases " в шаблоне, то зеленое {{documentation}}поле в шаблоне автоматически это обнаружит и покажет ссылки на эти страницы в своем заголовке. Для получения дополнительной информации см. Wikipedia:Template sandbox and test cases .
Когда несколько шаблонов работают вместе или очень похожи, то часто бывает понятнее и проще поддерживать одну страницу документации, которая документирует их вместе. Самый простой способ сделать это — создать полную страницу документации в одном из шаблонов, а затем сделать «мягкие перенаправления» из других шаблонов. Например, см.: {{ wrap }} .
Если подстраница документации не создана, а шаблон используется с параметром на фактической странице шаблона, то для размещения самого шаблона в категории добавьте внутри шаблона документации после контента. Например, для размещения на фактической странице шаблона:{{documentation}}|content=[[Category:Category name]]
<!--Последняя строка кода вашего шаблона--> < noinclude > {{ Documentation | content = <!-- документация шаблона -->[[ Категория : Имя категории ]] [[ Категория : Имя категории2 ]] }}</ noinclude >Когда отображаемый шаблон будет ссылаться на страницу, которая может служить документацией, то отдельная документация излишня и не нуждается в создании. Например, шаблон-заглушка, использующий шаблон {{ asbox }} в качестве основы, уже отобразит предварительно загруженную общую документацию для всех шаблонов-заглушек, использующих этот шаблон, и не будет нуждаться в дополнительной документации.
Вот несколько советов, которые облегчат написание документации:
<ref group="note">...</ref> } } . Этот пример записан как {{ tag |ref|params=group="note"}}<nowiki />тег:[[<nowiki />example]]становится [[пример]],[<nowiki />http://en.wikipedia.org no link][http://en.wikipedia.org нет ссылки]. Подробности смотрите в WP:NOWIKI .{{cat|Templates with incorrect parameter syntax}}становится Category:Templates с неправильным синтаксисом параметров .< includeonly >{{ sandbox other ||{{ testcases other || <!-- Категории ниже этой строки, пожалуйста; интервики в Wikidata -->}}}}</ включить только >{{ Какой - то шаблон инфобокса (дочерний) | child = <includeonly> да </includeonly> | label1 = Привет | data1 = Мир } } < noinclude > { { документация } } < / noinclude >