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

* [[User:Karibekov Vladislav Y.|<i>''Карибеков В. Ю.</i>'']]

* [[У:Sunpriat|Sunpriat]]  — могу помочь с таблицами <nowiki><templatedata></templatedata></nowiki> (для визуального редактора)

* Для каждого шаблона должны быть даны как минимум ''синтаксис'' (или просто описание параметров) или ''примеры использования'', а лучше  — и то, и другое (см. некоторые рекомендации на этот счёт ниже). Содержательные, детально прописанные для разных случаев примеры бывают очень полезны.

* О добавлении TemplateData в шаблоны для возможности редактирования их вида на страницах при помощи визуального редактора см. [[{{ссылка на раздел|Википедия:Визуальный редактор#Шаблоны]]}}.

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

* Раздел «Назначение» в документации избыточен  — со слов о том, для чего нужен шаблон, документация и так начинается. Раздел «Использование» должен быть посвящен тому, ''как'' использовать, а не ''зачем''.

* Для нескольких шаблонов из одного «семейства» (группы близких по внешнему виду или связанных по смыслу шаблонов) можно давать общую документацию (например, документации семейства шаблонов {{t|lang|text=lang-''x''}} и группы шаблонов {{t|столбцы}}), либо общую навигацию (в том числе через навигационные шаблоны, например {{t|Языковые шаблоны}}). При этом чтобы в такой документации упомянуть имя текущего шаблона, можно обойтись без [[Википедия:Переменные|специальных переменных]]  — достаточно написать {{tc|t}}. В блоках навигации по группе шаблонов используйте для ссылок на шаблоны шаблон {{t|tnav}} (например, {{tc|tnav|''шаблон''}}), и тогда название шаблона, на странице которого вы находитесь, будет выделен жирным.

** тег {{tago|pre}}, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, а поэтому, если разметка необходима, нужно либо, вместо использования {{tago|pre}}, начинать каждуюпервую строку примера с пробела, либо использовать шаблон {{t|pre}} (это удобно для однострочных шаблонов).{{pb

* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и пр.). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{t|флаг}}, а можно представить единой записью, как в документации шаблона {{t|перенесено с}}. Часто хорошая идея  — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). Не путайте при этом ''демонстрацию синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен на странице [[{{ссылка на раздел|Шаблон:Tc#В оформлении документации]]}}.

* Не упоминайте названия шаблонов в их собственных документациях при помощи шаблона {{t|tl}}, чтобы избежать появления некрасивого жирного серого текста. Используйте шаблон {{t|t}}  — можно без параметров. При первом упоминании шаблона можно взять его символическую запись в полужирное начертание, как это делается в статьях с предметом статьи: <code><nowiki>'''{{t}}'''</nowiki></code> или <code><nowiki>'''{{t||u}}'''</nowiki></code> (с первой прописной).

* Названия параметров обычно записываются со строчной буквы, при необходимости в них используются пробелы. Что касается названий самих шаблонов  — дело вкуса, но вряд ли названия узкоспециальных шаблонов технического характера (как то: {{t|lang-en}}, {{t|примечания}}) стоит писать с прописной. В то же время в названиях шаблонов-карточек (как то: {{t|Персона}}, {{t|Фильм}}) устоялась первая прописная.

* Ещё одна мелочь  — как в коде вызова многострочных шаблонов отбивать вертикальные черты от начала строк, а названия параметров  — от вертикальных черт. В английском разделе часто либо нет отбития вовсе, либо отбиваются названия параметров от вертикальных черт на один символ. У нас в этом деле разнобой.{{pb