Проект:Технические работы/Шаблоны/Документирование

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

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

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

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

Для шаблонов, которым не требуется подробная и/или часто обновляемая документация, может использоваться конструкция <noinclude>{{doc-inline}}</noinclude> для размещения документации прямо в тексте шаблона.

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

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

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

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

• Раздел «Назначение» в документации избыточен — со слов о том, для чего нужен шаблон, документация и так начинается. Раздел «Использование» должен быть посвящен тому, как использовать, а не зачем.
• Оглавление, если документация не занимает очень много места, выводите справа при помощи шаблона {{TOC right}} или удаляйте при помощи слова __NOTOC__ (например, в самом начале документации).
• Оформляйте список перенаправлений на шаблон (шорткатов) при помощи шаблона {{днш}}, размещая его под описанием предназначения шаблона или внизу.
• Раздел TemplateData, или «Параметры шаблона для визуального редактора», помещайте вниз, под разделом «См. также» (см. вопрос на форуме). На странице документации его всё равно никто не читает, если есть вручную свёрстанная документация.
• Для нескольких шаблонов из одного «семейства» (группы близких по внешнему виду или связанных по смыслу шаблонов) можно давать общую документацию (например, документации семейства шаблонов {{lang-x}} и группы шаблонов {{столбцы}}), либо общую навигацию (в том числе через навигационные шаблоны, например {{Языковые шаблоны}}). При этом чтобы в такой документации упомянуть имя текущего шаблона, можно обойтись без специальных переменных — достаточно написать {{t}}. В блоках навигации по группе шаблонов используйте для ссылок на шаблоны шаблон {{tnav}} (например, {{tnav|шаблон}}), и тогда название шаблона, на странице которого вы находитесь, будет выделен жирным.
• Чем уже сфера применения шаблона, тем хуже скоординирована работа над ним между разными участниками. Для шаблонов, не отличающихся большим вниманием к себе, можно прямо в тексте документации создать раздел «Необходимо/Можно сделать», где описать насущные потребности. Если вы считаете, что необходимо внести какое-то изменение в малоизвестный шаблон, но в обсуждении никто не отвечает, этим тоже можно поделиться со «случайными гостями» на странице документации.

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

• В шаблонах, предназначенных для обычных редакторов, шаблон и его параметры предпочтительно называть на русском языке (хотя у латиницы есть тот плюс, что не приходится переключать раскладку клавиатуры при вводе названия шаблона / его параметров).
• Есть несколько способов представить код примера использования шаблона (или его синтаксиса) в документации. Это:
  • тег <pre>, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, поэтому, если разметка необходима, нужно либо, вместо использования <pre>, начинать каждую строку примера с пробела, либо использовать шаблон {{tpre}} (это удобно для однострочных шаблонов).
    Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{highlight}} или {{oncolor}} (так сделано, например, в документациях шаблонов {{переход}} и {{ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{tpre}}:

    {{перенесено с|Вики-страница|подпись и/или текст в конце|текст=Текст вместо «Перенесено со страницы»}}

  • комбинация тегов <code> и <nowiki>, создающая маленькие поля вокруг кода.
    Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki></nowiki></code>, можно воспользоваться шаблоном {{tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{пример}} и аналогичные (в том числе {{стопка примеров}}, {{таблица примеров}}; покликайте по ссылкам в разделах «См. также»).
    Пример синтаксиса шаблона, оформленного с помощью {{tc}}:
    {{переход|#Раздел или #якорь|тип значка|Название раздела}}
• Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{флаг}}, а можно представить единой записью, как в документации шаблона {{перенесено с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте представление синтаксиса шаблона с примером его использования. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке Шаблон:Tc § В оформлении документации.
• Для описания параметров (полей) крупных шаблонов, кроме списков / таблиц, можно пользоваться хорошо оформленным шаблоном {{описание шаблона}} (как это будет выглядеть, см. здесь).
• Для упоминания шаблонов используйте шаблон {{t}}: {{t|пример}} → {{пример}}.
• Названия параметров обычно записываются со строчной буквы, при необходимости в них используются пробелы. Что касается названий самих шаблонов — дело вкуса, но вряд ли названия узкоспециальных шаблонов технического характера (как то: {{lang-en}}, {{примечания}}) стоит писать с прописной. В то же время в названиях шаблонов-карточек (как то: {{Персона}}, {{Фильм}}) устоялась первая прописная.
• Ещё одна мелочь — как в коде включения многострочных шаблонов отбивать вертикальные черты от начала строк, а названия параметров — от вертикальных черт. В английском разделе часто либо нет отбития вовсе, либо отбиваются названия параметров от вертикальных черт на один символ. У нас в этом деле разнобой.
  В свою очередь, в длинных однострочных шаблонах для лучшей читаемости целесообразно отбивать каждый следующий параметр пробелом, как в шаблоне {{cite web}}: {{cite web |url= |title= |author= |date= |work= |publisher= |accessdate=2016-01-27 |lang=}}.