Проект:Документирование шаблонов

Википроект «Документирование шаблонов» создан для выработки общих правил пользования шаблонами (уместность применения, правила установки и снятия и т. д.). На данный момент многие шаблоны не имеют соответствующих отметок, что необходимо исправлять. Главная категория для работы — Шаблон:Cl.

На страницу задокументированного шаблона ставится пометка <noinclude>{{doc}}</noinclude>. При этом создаётся ссылка на страницу документации. После написания документации на соответствующей странице ссылка автоматически будет заменена документацией. Обратите внимание, что редактирование документации не вызовет перерисовки всех страниц, использующих шаблон.

Сверху страницы документации также следует добавлять Шаблон:Tlc для создания простой навигации между шаблоном, его страницей документации и обсуждением. Помещать его на страницу шаблона не нужно, имеющиеся в нём ссылки уже есть в шаблоне {{doc}}.

См. список задокументированных шаблонов, категория документаций шаблонов.

Для шаблонов, которым не требуется подробная и/или часто обновляемая документация, может использоваться конструкция <noinclude>{{safesubst:#invoke: Template call code | withoutParams }}</noinclude> для размещения документации прямо в тексте шаблона.

Обратите внимание на /Защищённые шаблоны без документации.

Некоторые тонкости работы и рекомендации

• Для каждого шаблона должны быть даны как минимум синтаксис (или просто описание параметров) или примеры использования, а лучше — и то, и другое (см. некоторые рекомендации на этот счёт ниже). Содержательные, детально прописанные для разных случаев примеры бывают очень полезны.
• Для шаблонов-карточек и не только полезно предлагать заготовку для копирования, которую люди бы вставляли в страницы. В заготовке есть смысл не удалять всё содержимое после знаков «=», а оставить полезную разметку (например, шаблоны, которые обычно используются в этих полях; пример) и те критичные замечания, которые некоторые участники по невнимательности могут проигнорировать.
• В Шаблон:Категории перечислены разные инструменты, которые могут пригодиться в процессе документирования.
• О добавлении TemplateData в шаблоны для возможности редактирования их вида на страницах при помощи визуального редактора см. Шаблон:Ссылка на раздел.
• От того, как вы категоризуете ваш шаблон (см. Проект:Технические работы/Шаблоны/Категоризация), а ещё важнее — насколько обеспечите его связностью и информируете о его существовании остальных, в том числе будет зависеть его популярность. Не стесняйтесь пытаться популяризовать хорошие шаблоны в местах скопления людей (на форуме, в проекте, к которому он относится, и пр.) — многие хорошие шаблоны не используются, потому что люди о них просто не знают и им неоткуда узнать. Добавляйте шаблоны в соответствующие перечни, упомянутые на странице Википедия:Шаблоны, в разделы «См. также» документаций близких по предназначению шаблонов. Может даже понадобиться создать отдельную страницу в пространстве «Википедия», где будет рассказано про некоторый класс шаблонов, который до сих пор не был отмечен другими.
• Программистам следует помнить, что подавляющее большинство пользователей шаблонов не искушены в программировании, и в случае шаблонов, предназначенных для массового использования, следует давать объяснения «для чайников», снабжать их вспомогательными ссылками, не злоупотреблять терминологией.

Шаблон:^ Далее некоторые оформительские советы от Jack who built the house (можете добавить свои и тогда удалить моё имя).

Структура документации

• Раздел «Назначение» в документации избыточен — со слов о том, для чего нужен шаблон, документация и так начинается. Раздел «Использование» должен быть посвящен тому, как использовать, а не зачем.
• Оглавление, если документация не занимает очень много места, выводите справа при помощи шаблона {{safesubst:#invoke: Template call code | withoutParams }} или удаляйте при помощи слова Шаблон:Mwmw (например, в самом начале документации).
• Оформляйте список перенаправлений на шаблон (шорткатов) при помощи шаблона {{safesubst:#invoke: Template call code | withoutParams }}, размещая его под описанием предназначения шаблона или внизу.
• Раздел «TemplateData», или «Параметры шаблона для визуального редактора», помещайте вниз, под разделом «См. также» (см. вопрос на форуме). На странице документации его всё равно никто не читает, если есть вручную свёрстанная документация.
• Для нескольких шаблонов из одного «семейства» (группы близких по внешнему виду или связанных по смыслу шаблонов) можно давать общую документацию (например, документации семейства шаблонов {{safesubst:#invoke: Template call code | withoutParams }} и группы шаблонов {{safesubst:#invoke: Template call code | withoutParams }}), либо общую навигацию (в том числе через навигационные шаблоны, например {{safesubst:#invoke: Template call code | withoutParams }}). При этом чтобы в такой документации упомянуть имя текущего шаблона, можно обойтись без специальных переменных — достаточно написать Шаблон:Tcl. В блоках навигации по группе шаблонов используйте для ссылок на шаблоны шаблон {{safesubst:#invoke: Template call code | withoutParams }} (например, Шаблон:Tc), и тогда название шаблона, на странице которого вы находитесь, будет выделен жирным.
• Чем у́же сфера применения шаблона, тем хуже скоординирована работа над ним между разными участниками. Для шаблонов, не отличающихся большим вниманием к себе, можно прямо в тексте документации создать раздел «Необходимо/Можно сделать», где описать насущные потребности. Если вы считаете, что необходимо внести какое-то изменение в малоизвестный шаблон, но в обсуждении никто не отвечает, этим тоже можно поделиться со «случайными гостями» на странице документации.

Оформительские тонкости

• В шаблонах, предназначенных для обычных редакторов, шаблон и его параметры предпочтительно называть на русском языке (хотя у латиницы есть тот плюс, что не приходится переключать раскладку клавиатуры при вводе названия шаблонаШаблон:Sp/его параметров).
• Есть несколько способов представить код примера использования шаблона (или его синтаксиса) в документации. Это:
  • тег Шаблон:Tago, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, поэтому, если разметка необходима, нужно либо, вместо использования Шаблон:Tago, начинать каждую строку примера с пробела, либо использовать шаблон {{safesubst:#invoke: Template call code | withoutParams }} (это удобно для однострочных шаблонов).Шаблон:PbЧтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{safesubst:#invoke: Template call code | withoutParams }} или {{safesubst:#invoke: Template call code | withoutParams }} (так сделано, например, в документациях шаблонов {{safesubst:#invoke: Template call code | withoutParams }} и {{safesubst:#invoke: Template call code | withoutParams }}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{safesubst:#invoke: Template call code | withoutParams }}:Шаблон:Tpre
  • комбинация тегов Шаблон:Tago и Шаблон:Tago, создающая маленькие поля вокруг кода.Шаблон:PbЧтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki></nowiki></code>, можно воспользоваться шаблоном {{safesubst:#invoke: Template call code | withoutParams }} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{safesubst:#invoke: Template call code | withoutParams }} и аналогичные (в том числе {{safesubst:#invoke: Template call code | withoutParams }}, {{safesubst:#invoke: Template call code | withoutParams }}; покликайте по ссылкам в разделах «См. также»).Шаблон:PbПример синтаксиса шаблона, оформленного с помощью {{safesubst:#invoke: Template call code | withoutParams }}:Шаблон:PbШаблон:TclШаблон:^
• Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{safesubst:#invoke: Template call code | withoutParams }}, а можно представить единой записью, как в документации шаблона {{safesubst:#invoke: Template call code | withoutParams }}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте представление синтаксиса шаблона с примером его использования. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке Шаблон:Ссылка на раздел.
• Для описания параметров (полей) крупных шаблонов, кроме списковШаблон:Sp/таблиц, можно пользоваться хорошо оформленным шаблоном {{safesubst:#invoke: Template call code | withoutParams }} (как это будет выглядеть, см. здесь).
• Для упоминания шаблонов используйте шаблон {{safesubst:#invoke: Template call code | withoutParams }}: Шаблон:Пример.
• Названия параметров обычно записываются со строчной буквы, при необходимости в них используются пробелы. Что касается названий самих шаблонов — дело вкуса, но вряд ли названия узкоспециальных шаблонов технического характера (как то: {{safesubst:#invoke: Template call code | withoutParams }}, {{safesubst:#invoke: Template call code | withoutParams }}) стоит писать с прописной. В то же время в названиях шаблонов-карточек (как то: {{safesubst:#invoke: Template call code | withoutParams }}, {{safesubst:#invoke: Template call code | withoutParams }}) устоялась первая прописная.
• Ещё одна мелочь — как в коде включения многострочных шаблонов отбивать вертикальные черты от начала строк, а названия параметров — от вертикальных черт. В английском разделе часто либо нет отбития вовсе, либо отбиваются названия параметров от вертикальных черт на один символ. У нас в этом деле разнобой.Шаблон:PbВ свою очередь, в длинных однострочных шаблонах для лучшей читаемости целесообразно отбивать каждый следующий параметр пробелом, как в шаблоне {{safesubst:#invoke: Template call code | withoutParams }}: Шаблон:Tc.

См. также

• Проект:Технические работы/Оформление шаблонов
• en:Wikipedia:Protection policy#Template protection, en:Wikipedia:High-risk templates#Documentation and padlock, en:Wikipedia:Template documentation#What to include
• mw:Extension:TemplateData#Editing data, mw:Help:TemplateData (описание может отставать от добавленных возможностей), en:Wikipedia:TemplateData/Tutorial
• en:Template:Documentation/doc#Automatic functions - en:Template:Documentation/preload, en:Template:Doc-code
• Ш:onLua Ш:onTS
• Mediawiki:Editnotice-10 при редактировании /doc показывает рекомендации
• Ш:module rating
• Ш:СИШ Ш:High-use Ш:Используйте песочницу
• Ш:esoteric Ш:Устаревший шаблон Ш:Другие названия шаблона