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

Andras в 13:11, 1 марта 2024

2024-03-01T13:11:07Z

← Предыдущая версия		Версия от 13:11, 1 марта 2024
Строка 25:		Строка 25:
	=== Структура документации ===		=== Структура документации ===
	* Раздел «Назначение» в документации избыточен — со слов о том, для чего нужен шаблон, документация и так начинается. Раздел «Использование» должен быть посвящен тому, ''как'' использовать, а не ''зачем''.		* Раздел «Назначение» в документации избыточен — со слов о том, для чего нужен шаблон, документация и так начинается. Раздел «Использование» должен быть посвящен тому, ''как'' использовать, а не ''зачем''.
	* Оглавление, если документация не занимает очень много места, выводите справа при помощи шаблона {{Tl\|TOC right}} или удаляйте при помощи слова {{~~mwmw~~\|NOTOC}} (например, в самом начале документации).		* Оглавление, если документация не занимает очень много места, выводите справа при помощи шаблона {{Tl\|TOC right}} или удаляйте при помощи слова {{Mwmw\|NOTOC}} (например, в самом начале документации).
	* Оформляйте список перенаправлений на шаблон (шорткатов) при помощи шаблона {{Tl\|днш}}, размещая его под описанием предназначения шаблона или внизу.		* Оформляйте список перенаправлений на шаблон (шорткатов) при помощи шаблона {{Tl\|днш}}, размещая его под описанием предназначения шаблона или внизу.
	* Раздел «TemplateData», или «Параметры шаблона для визуального редактора», помещайте вниз, под разделом «См. также» (см. [[РуСказки:Форум/Архив/Технический/2016/03#TemplateData в документациях шаблонов\|вопрос на форуме]]). На странице документации его всё равно никто не читает, если есть вручную свёрстанная документация.		* Раздел «TemplateData», или «Параметры шаблона для визуального редактора», помещайте вниз, под разделом «См. также» (см. [[РуСказки:Форум/Архив/Технический/2016/03#TemplateData в документациях шаблонов\|вопрос на форуме]]). На странице документации его всё равно никто не читает, если есть вручную свёрстанная документация.

Andras в 09:25, 1 марта 2024

2024-03-01T09:25:14Z

← Предыдущая версия		Версия от 09:25, 1 марта 2024
Строка 16:		Строка 16:
	* Для [[Википедия:Шаблоны-карточки\|шаблонов-карточек]] и не только полезно предлагать ''заготовку для копирования'', которую люди бы вставляли в страницы. В заготовке есть смысл не удалять всё содержимое после знаков «=», а оставить полезную разметку (например, шаблоны, которые обычно используются в этих полях; [[Шаблон:Учёный#С шаблонами\|пример]]) и те критичные замечания, которые некоторые участники по невнимательности могут проигнорировать.		* Для [[Википедия:Шаблоны-карточки\|шаблонов-карточек]] и не только полезно предлагать ''заготовку для копирования'', которую люди бы вставляли в страницы. В заготовке есть смысл не удалять всё содержимое после знаков «=», а оставить полезную разметку (например, шаблоны, которые обычно используются в этих полях; [[Шаблон:Учёный#С шаблонами\|пример]]) и те критичные замечания, которые некоторые участники по невнимательности могут проигнорировать.
	* В {{категории\|Шаблоны:Для документирования шаблонов}} перечислены разные инструменты, которые могут пригодиться в процессе документирования.		* В {{категории\|Шаблоны:Для документирования шаблонов}} перечислены разные инструменты, которые могут пригодиться в процессе документирования.
	* О добавлении TemplateData в шаблоны для возможности редактирования их вида на страницах при помощи визуального редактора см. {{~~ссылка~~ на раздел\|~~Википедия~~:Визуальный редактор#Шаблоны}}.		* О добавлении TemplateData в шаблоны для возможности редактирования их вида на страницах при помощи визуального редактора см. {{Ссылка на раздел\|РуСказки:Визуальный редактор#Шаблоны}}.
	* От того, как вы категоризуете ваш шаблон (см. [[Проект:Технические работы/Шаблоны/Категоризация]]), а ещё важнее — насколько обеспечите его [[Википедия:Связность статей\|связностью]] и информируете о его существовании остальных, в том числе будет зависеть его популярность. Не стесняйтесь пытаться популяризовать хорошие шаблоны в местах скопления людей (на [[Википедия:Форум\|форуме]], в [[Википедия:Проекты\|проекте]], к которому он относится, и пр.) — многие хорошие шаблоны не используются, потому что люди о них просто не знают и им неоткуда узнать. Добавляйте шаблоны в соответствующие перечни, упомянутые на странице [[Википедия:Шаблоны]], в разделы «См. также» документаций близких по предназначению шаблонов. Может даже понадобиться создать отдельную страницу в пространстве «Википедия», где будет рассказано про некоторый класс шаблонов, который до сих пор не был отмечен другими.		* От того, как вы категоризуете ваш шаблон (см. [[Проект:Технические работы/Шаблоны/Категоризация]]), а ещё важнее — насколько обеспечите его [[Википедия:Связность статей\|связностью]] и информируете о его существовании остальных, в том числе будет зависеть его популярность. Не стесняйтесь пытаться популяризовать хорошие шаблоны в местах скопления людей (на [[Википедия:Форум\|форуме]], в [[Википедия:Проекты\|проекте]], к которому он относится, и пр.) — многие хорошие шаблоны не используются, потому что люди о них просто не знают и им неоткуда узнать. Добавляйте шаблоны в соответствующие перечни, упомянутые на странице [[Википедия:Шаблоны]], в разделы «См. также» документаций близких по предназначению шаблонов. Может даже понадобиться создать отдельную страницу в пространстве «Википедия», где будет рассказано про некоторый класс шаблонов, который до сих пор не был отмечен другими.
	* Программистам следует помнить, что подавляющее большинство пользователей шаблонов не искушены в программировании, и в случае шаблонов, предназначенных для массового использования, следует давать объяснения «для чайников», снабжать их вспомогательными ссылками, не злоупотреблять терминологией.		* Программистам следует помнить, что подавляющее большинство пользователей шаблонов не искушены в программировании, и в случае шаблонов, предназначенных для массового использования, следует давать объяснения «для чайников», снабжать их вспомогательными ссылками, не злоупотреблять терминологией.
Строка 40:		Строка 40:
	}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац		}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац
	}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}		}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}
	* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{Tl\|~~флаг~~}}, а можно представить единой записью, как в документации шаблона {{Tl\|~~перенесено~~ с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте ''представление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке {{~~ссылка~~ на раздел\|Шаблон:Tc#В оформлении документации}}.		* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{Tl\|Флаг}}, а можно представить единой записью, как в документации шаблона {{Tl\|Перенесено с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте ''представление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке {{Ссылка на раздел\|Шаблон:Tc#В оформлении документации}}.
	* Для описания параметров (полей) крупных шаблонов, кроме списков{{sp/}}таблиц, можно пользоваться хорошо оформленным шаблоном {{Tl\|~~описание~~ шаблона}} (как это будет выглядеть, см. [[Шаблон:Публикация#Поля\|здесь]]).		* Для описания параметров (полей) крупных шаблонов, кроме списков{{sp/}}таблиц, можно пользоваться хорошо оформленным шаблоном {{Tl\|Описание шаблона}} (как это будет выглядеть, см. [[Шаблон:Публикация#Поля\|здесь]]).
	* Для упоминания шаблонов используйте шаблон {{Tl\|Tl}}: {{Пример\|Tl\|Пример}}.		* Для упоминания шаблонов используйте шаблон {{Tl\|Tl}}: {{Пример\|Tl\|Пример}}.
	* Названия параметров обычно записываются со строчной буквы, при необходимости в них используются пробелы. Что касается названий самих шаблонов — дело вкуса, но вряд ли названия узкоспециальных шаблонов технического характера (как то: {{Tl\|Lang-en}}, {{Tl\|Примечания}}) стоит писать с прописной. В то же время в названиях шаблонов-карточек (как то: {{Tl\|Персона}}, {{Tl\|Фильм}}) устоялась первая прописная.		* Названия параметров обычно записываются со строчной буквы, при необходимости в них используются пробелы. Что касается названий самих шаблонов — дело вкуса, но вряд ли названия узкоспециальных шаблонов технического характера (как то: {{Tl\|Lang-en}}, {{Tl\|Примечания}}) стоит писать с прописной. В то же время в названиях шаблонов-карточек (как то: {{Tl\|Персона}}, {{Tl\|Фильм}}) устоялась первая прописная.

Andras в 14:03, 29 февраля 2024

2024-02-29T14:03:32Z

← Предыдущая версия		Версия от 14:03, 29 февраля 2024
Строка 36:		Строка 36:
	** тег {{Tago\|pre}}, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, поэтому, если разметка необходима, нужно либо, вместо использования {{Tago\|pre}}, начинать каждую строку примера с пробела, либо использовать шаблон {{Tl\|Tpre}} (это удобно для однострочных шаблонов).{{Абзац		** тег {{Tago\|pre}}, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, поэтому, если разметка необходима, нужно либо, вместо использования {{Tago\|pre}}, начинать каждую строку примера с пробела, либо использовать шаблон {{Tl\|Tpre}} (это удобно для однострочных шаблонов).{{Абзац
	}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|Tpre}}:{{Tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}		}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|Tpre}}:{{Tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}
	** комбинация тегов {{~~tago~~\|code}} и {{~~tago~~\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац		** комбинация тегов {{Tago\|code}} и {{Tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац
	}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|Пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац		}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|Пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац
	}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац		}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац

Andras в 10:40, 29 февраля 2024

2024-02-29T10:40:09Z

← Предыдущая версия		Версия от 10:40, 29 февраля 2024
Строка 34:		Строка 34:
	* В шаблонах, предназначенных для обычных редакторов, шаблон и его параметры предпочтительно называть на русском языке (хотя у латиницы есть тот плюс, что не приходится переключать раскладку клавиатуры при вводе названия шаблона{{Sp/}}его параметров).		* В шаблонах, предназначенных для обычных редакторов, шаблон и его параметры предпочтительно называть на русском языке (хотя у латиницы есть тот плюс, что не приходится переключать раскладку клавиатуры при вводе названия шаблона{{Sp/}}его параметров).
	* Есть несколько способов представить код примера использования шаблона (или его синтаксиса) в документации. Это:		* Есть несколько способов представить код примера использования шаблона (или его синтаксиса) в документации. Это:
	** тег {{Tago\|pre}}, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, поэтому, если разметка необходима, нужно либо, вместо использования {{Tago\|pre}}, начинать каждую строку примера с пробела, либо использовать шаблон {{Tl\|~~tpre~~}} (это удобно для однострочных шаблонов).{{Абзац		** тег {{Tago\|pre}}, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, поэтому, если разметка необходима, нужно либо, вместо использования {{Tago\|pre}}, начинать каждую строку примера с пробела, либо использовать шаблон {{Tl\|Tpre}} (это удобно для однострочных шаблонов).{{Абзац
	}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|~~tpre~~}}:{{~~tpre~~\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}		}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|Tpre}}:{{Tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}
	** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац		** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац
	}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|Пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац		}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|Пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац

Andras в 09:23, 29 февраля 2024

2024-02-29T09:23:12Z

← Предыдущая версия		Версия от 09:23, 29 февраля 2024
Строка 37:		Строка 37:
	}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|tpre}}:{{tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}		}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|tpre}}:{{tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}
	** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац		** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац
	}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|~~пример~~}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац		}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|Пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац
	}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац		}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац
	}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}		}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}

Andras в 09:19, 29 февраля 2024

2024-02-29T09:19:19Z

← Предыдущая версия		Версия от 09:19, 29 февраля 2024
Строка 37:		Строка 37:
	}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|tpre}}:{{tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}		}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|tpre}}:{{tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}
	** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац		** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац
	}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац		}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац
	}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|tc}}:{{Абзац		}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац
	}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}		}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}
	* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{Tl\|флаг}}, а можно представить единой записью, как в документации шаблона {{Tl\|перенесено с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте ''представление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке {{ссылка на раздел\|Шаблон:Tc#В оформлении документации}}.		* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{Tl\|флаг}}, а можно представить единой записью, как в документации шаблона {{Tl\|перенесено с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте ''представление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке {{ссылка на раздел\|Шаблон:Tc#В оформлении документации}}.

Andras в 09:13, 29 февраля 2024

2024-02-29T09:13:20Z

← Предыдущая версия		Версия от 09:13, 29 февраля 2024
Строка 4:		Строка 4:
	На страницу задокументированного шаблона ставится пометка <code><nowiki><noinclude>{{Doc}}</noinclude></nowiki></code>. При этом создаётся ссылка на страницу документации. После написания документации на соответствующей странице ссылка автоматически будет заменена документацией. Обратите внимание, что редактирование документации не вызовет перерисовки всех страниц, использующих шаблон.		На страницу задокументированного шаблона ставится пометка <code><nowiki><noinclude>{{Doc}}</noinclude></nowiki></code>. При этом создаётся ссылка на страницу документации. После написания документации на соответствующей странице ссылка автоматически будет заменена документацией. Обратите внимание, что редактирование документации не вызовет перерисовки всех страниц, использующих шаблон.

	Сверху страницы документации также следует добавлять {{~~Tlc~~\|Docpage}} для создания простой навигации между шаблоном, его страницей документации и обсуждением. Помещать его на страницу шаблона не нужно, имеющиеся в нём ссылки уже есть в шаблоне {{Tl\|Doc}}.		Сверху страницы документации также следует добавлять {{Tcl\|Docpage}} для создания простой навигации между шаблоном, его страницей документации и обсуждением. Помещать его на страницу шаблона не нужно, имеющиеся в нём ссылки уже есть в шаблоне {{Tl\|Doc}}.

	См. [http://ru.wikipedia.org/w/index.php?title=Служебная:WhatLinksHere/Шаблон:Doc&namespace=10&hideredirs=1&hidelinks=1&limit=500 список задокументированных шаблонов], [[:Категория:Шаблоны:Документация\|категория документаций шаблонов]].		См. [http://ru.wikipedia.org/w/index.php?title=Служебная:WhatLinksHere/Шаблон:Doc&namespace=10&hideredirs=1&hidelinks=1&limit=500 список задокументированных шаблонов], [[:Категория:Шаблоны:Документация\|категория документаций шаблонов]].

Andras в 18:45, 26 февраля 2024

2024-02-26T18:45:53Z

← Предыдущая версия		Версия от 18:45, 26 февраля 2024
Строка 28:		Строка 28:
	* Оформляйте список перенаправлений на шаблон (шорткатов) при помощи шаблона {{Tl\|днш}}, размещая его под описанием предназначения шаблона или внизу.		* Оформляйте список перенаправлений на шаблон (шорткатов) при помощи шаблона {{Tl\|днш}}, размещая его под описанием предназначения шаблона или внизу.
	* Раздел «TemplateData», или «Параметры шаблона для визуального редактора», помещайте вниз, под разделом «См. также» (см. [[РуСказки:Форум/Архив/Технический/2016/03#TemplateData в документациях шаблонов\|вопрос на форуме]]). На странице документации его всё равно никто не читает, если есть вручную свёрстанная документация.		* Раздел «TemplateData», или «Параметры шаблона для визуального редактора», помещайте вниз, под разделом «См. также» (см. [[РуСказки:Форум/Архив/Технический/2016/03#TemplateData в документациях шаблонов\|вопрос на форуме]]). На странице документации его всё равно никто не читает, если есть вручную свёрстанная документация.
	* Для нескольких шаблонов из одного «семейства» (группы близких по внешнему виду или связанных по смыслу шаблонов) можно давать общую документацию (например, документации семейства шаблонов {{Tl\|~~lang~~\|text=lang-''x''}} и группы шаблонов {{Tl\|столбцы}}), либо общую навигацию (в том числе через навигационные шаблоны, например {{Tl\|Языковые шаблоны}}). При этом чтобы в такой документации упомянуть имя текущего шаблона, можно обойтись без [[Википедия:Переменные\|специальных переменных]] — достаточно написать {{Tcl\|Tl}}. В блоках навигации по группе шаблонов используйте для ссылок на шаблоны шаблон {{Tl\|tnav}} (например, {{Tc\|tnav\|''шаблон''}}), и тогда название шаблона, на странице которого вы находитесь, будет выделен жирным.		* Для нескольких шаблонов из одного «семейства» (группы близких по внешнему виду или связанных по смыслу шаблонов) можно давать общую документацию (например, документации семейства шаблонов {{Tl\|Lang\|text=lang-''x''}} и группы шаблонов {{Tl\|столбцы}}), либо общую навигацию (в том числе через навигационные шаблоны, например {{Tl\|Языковые шаблоны}}). При этом чтобы в такой документации упомянуть имя текущего шаблона, можно обойтись без [[Википедия:Переменные\|специальных переменных]] — достаточно написать {{Tcl\|Tl}}. В блоках навигации по группе шаблонов используйте для ссылок на шаблоны шаблон {{Tl\|tnav}} (например, {{Tc\|tnav\|''шаблон''}}), и тогда название шаблона, на странице которого вы находитесь, будет выделен жирным.
	* Чем у́же сфера применения шаблона, тем хуже скоординирована работа над ним между разными участниками. Для шаблонов, не отличающихся большим вниманием к себе, можно прямо в тексте документации создать раздел «Необходимо/Можно сделать», где описать насущные потребности. Если вы считаете, что необходимо внести какое-то изменение в малоизвестный шаблон, но в обсуждении никто не отвечает, этим тоже можно поделиться со «случайными гостями» на странице документации.		* Чем у́же сфера применения шаблона, тем хуже скоординирована работа над ним между разными участниками. Для шаблонов, не отличающихся большим вниманием к себе, можно прямо в тексте документации создать раздел «Необходимо/Можно сделать», где описать насущные потребности. Если вы считаете, что необходимо внести какое-то изменение в малоизвестный шаблон, но в обсуждении никто не отвечает, этим тоже можно поделиться со «случайными гостями» на странице документации.

Andras в 15:03, 26 февраля 2024

2024-02-26T15:03:04Z

Andras в 13:30, 26 февраля 2024

2024-02-26T13:30:35Z

← Предыдущая версия		Версия от 09:25, 1 марта 2024
Строка 16:		Строка 16:
	* Для [[Википедия:Шаблоны-карточки\|шаблонов-карточек]] и не только полезно предлагать ''заготовку для копирования'', которую люди бы вставляли в страницы. В заготовке есть смысл не удалять всё содержимое после знаков «=», а оставить полезную разметку (например, шаблоны, которые обычно используются в этих полях; [[Шаблон:Учёный#С шаблонами\|пример]]) и те критичные замечания, которые некоторые участники по невнимательности могут проигнорировать.		* Для [[Википедия:Шаблоны-карточки\|шаблонов-карточек]] и не только полезно предлагать ''заготовку для копирования'', которую люди бы вставляли в страницы. В заготовке есть смысл не удалять всё содержимое после знаков «=», а оставить полезную разметку (например, шаблоны, которые обычно используются в этих полях; [[Шаблон:Учёный#С шаблонами\|пример]]) и те критичные замечания, которые некоторые участники по невнимательности могут проигнорировать.
	* В {{категории\|Шаблоны:Для документирования шаблонов}} перечислены разные инструменты, которые могут пригодиться в процессе документирования.		* В {{категории\|Шаблоны:Для документирования шаблонов}} перечислены разные инструменты, которые могут пригодиться в процессе документирования.
	* О добавлении TemplateData в шаблоны для возможности редактирования их вида на страницах при помощи визуального редактора см. {{~~ссылка~~ на раздел\|~~Википедия~~:Визуальный редактор#Шаблоны}}.		* О добавлении TemplateData в шаблоны для возможности редактирования их вида на страницах при помощи визуального редактора см. {{Ссылка на раздел\|РуСказки:Визуальный редактор#Шаблоны}}.
	* От того, как вы категоризуете ваш шаблон (см. [[Проект:Технические работы/Шаблоны/Категоризация]]), а ещё важнее — насколько обеспечите его [[Википедия:Связность статей\|связностью]] и информируете о его существовании остальных, в том числе будет зависеть его популярность. Не стесняйтесь пытаться популяризовать хорошие шаблоны в местах скопления людей (на [[Википедия:Форум\|форуме]], в [[Википедия:Проекты\|проекте]], к которому он относится, и пр.) — многие хорошие шаблоны не используются, потому что люди о них просто не знают и им неоткуда узнать. Добавляйте шаблоны в соответствующие перечни, упомянутые на странице [[Википедия:Шаблоны]], в разделы «См. также» документаций близких по предназначению шаблонов. Может даже понадобиться создать отдельную страницу в пространстве «Википедия», где будет рассказано про некоторый класс шаблонов, который до сих пор не был отмечен другими.		* От того, как вы категоризуете ваш шаблон (см. [[Проект:Технические работы/Шаблоны/Категоризация]]), а ещё важнее — насколько обеспечите его [[Википедия:Связность статей\|связностью]] и информируете о его существовании остальных, в том числе будет зависеть его популярность. Не стесняйтесь пытаться популяризовать хорошие шаблоны в местах скопления людей (на [[Википедия:Форум\|форуме]], в [[Википедия:Проекты\|проекте]], к которому он относится, и пр.) — многие хорошие шаблоны не используются, потому что люди о них просто не знают и им неоткуда узнать. Добавляйте шаблоны в соответствующие перечни, упомянутые на странице [[Википедия:Шаблоны]], в разделы «См. также» документаций близких по предназначению шаблонов. Может даже понадобиться создать отдельную страницу в пространстве «Википедия», где будет рассказано про некоторый класс шаблонов, который до сих пор не был отмечен другими.
	* Программистам следует помнить, что подавляющее большинство пользователей шаблонов не искушены в программировании, и в случае шаблонов, предназначенных для массового использования, следует давать объяснения «для чайников», снабжать их вспомогательными ссылками, не злоупотреблять терминологией.		* Программистам следует помнить, что подавляющее большинство пользователей шаблонов не искушены в программировании, и в случае шаблонов, предназначенных для массового использования, следует давать объяснения «для чайников», снабжать их вспомогательными ссылками, не злоупотреблять терминологией.
Строка 40:		Строка 40:
	}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац		}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац
	}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}		}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}
	* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{Tl\|~~флаг~~}}, а можно представить единой записью, как в документации шаблона {{Tl\|~~перенесено~~ с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте ''представление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке {{~~ссылка~~ на раздел\|Шаблон:Tc#В оформлении документации}}.		* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{Tl\|Флаг}}, а можно представить единой записью, как в документации шаблона {{Tl\|Перенесено с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте ''представление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке {{Ссылка на раздел\|Шаблон:Tc#В оформлении документации}}.
	* Для описания параметров (полей) крупных шаблонов, кроме списков{{sp/}}таблиц, можно пользоваться хорошо оформленным шаблоном {{Tl\|~~описание~~ шаблона}} (как это будет выглядеть, см. [[Шаблон:Публикация#Поля\|здесь]]).		* Для описания параметров (полей) крупных шаблонов, кроме списков{{sp/}}таблиц, можно пользоваться хорошо оформленным шаблоном {{Tl\|Описание шаблона}} (как это будет выглядеть, см. [[Шаблон:Публикация#Поля\|здесь]]).
	* Для упоминания шаблонов используйте шаблон {{Tl\|Tl}}: {{Пример\|Tl\|Пример}}.		* Для упоминания шаблонов используйте шаблон {{Tl\|Tl}}: {{Пример\|Tl\|Пример}}.
	* Названия параметров обычно записываются со строчной буквы, при необходимости в них используются пробелы. Что касается названий самих шаблонов — дело вкуса, но вряд ли названия узкоспециальных шаблонов технического характера (как то: {{Tl\|Lang-en}}, {{Tl\|Примечания}}) стоит писать с прописной. В то же время в названиях шаблонов-карточек (как то: {{Tl\|Персона}}, {{Tl\|Фильм}}) устоялась первая прописная.		* Названия параметров обычно записываются со строчной буквы, при необходимости в них используются пробелы. Что касается названий самих шаблонов — дело вкуса, но вряд ли названия узкоспециальных шаблонов технического характера (как то: {{Tl\|Lang-en}}, {{Tl\|Примечания}}) стоит писать с прописной. В то же время в названиях шаблонов-карточек (как то: {{Tl\|Персона}}, {{Tl\|Фильм}}) устоялась первая прописная.

← Предыдущая версия		Версия от 14:03, 29 февраля 2024
Строка 36:		Строка 36:
	** тег {{Tago\|pre}}, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, поэтому, если разметка необходима, нужно либо, вместо использования {{Tago\|pre}}, начинать каждую строку примера с пробела, либо использовать шаблон {{Tl\|Tpre}} (это удобно для однострочных шаблонов).{{Абзац		** тег {{Tago\|pre}}, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, поэтому, если разметка необходима, нужно либо, вместо использования {{Tago\|pre}}, начинать каждую строку примера с пробела, либо использовать шаблон {{Tl\|Tpre}} (это удобно для однострочных шаблонов).{{Абзац
	}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|Tpre}}:{{Tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}		}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|Tpre}}:{{Tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}
	** комбинация тегов {{~~tago~~\|code}} и {{~~tago~~\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац		** комбинация тегов {{Tago\|code}} и {{Tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац
	}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|Пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац		}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|Пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац
	}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац		}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац

← Предыдущая версия		Версия от 09:23, 29 февраля 2024
Строка 37:		Строка 37:
	}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|tpre}}:{{tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}		}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|tpre}}:{{tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}
	** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац		** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац
	}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|~~пример~~}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац		}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|Пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац
	}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац		}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац
	}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}		}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}

← Предыдущая версия		Версия от 09:19, 29 февраля 2024
Строка 37:		Строка 37:
	}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|tpre}}:{{tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}		}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|tpre}}:{{tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}
	** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац		** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац
	}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац		}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|Tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац
	}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|tc}}:{{Абзац		}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|Tc}}:{{Абзац
	}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}		}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}
	* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{Tl\|флаг}}, а можно представить единой записью, как в документации шаблона {{Tl\|перенесено с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте ''представление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке {{ссылка на раздел\|Шаблон:Tc#В оформлении документации}}.		* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{Tl\|флаг}}, а можно представить единой записью, как в документации шаблона {{Tl\|перенесено с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте ''представление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке {{ссылка на раздел\|Шаблон:Tc#В оформлении документации}}.

← Предыдущая версия		Версия от 15:03, 26 февраля 2024
Строка 4:		Строка 4:
	На страницу задокументированного шаблона ставится пометка <code><nowiki><noinclude>{{Doc}}</noinclude></nowiki></code>. При этом создаётся ссылка на страницу документации. После написания документации на соответствующей странице ссылка автоматически будет заменена документацией. Обратите внимание, что редактирование документации не вызовет перерисовки всех страниц, использующих шаблон.		На страницу задокументированного шаблона ставится пометка <code><nowiki><noinclude>{{Doc}}</noinclude></nowiki></code>. При этом создаётся ссылка на страницу документации. После написания документации на соответствующей странице ссылка автоматически будет заменена документацией. Обратите внимание, что редактирование документации не вызовет перерисовки всех страниц, использующих шаблон.

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

	См. [http://ru.wikipedia.org/w/index.php?title=Служебная:WhatLinksHere/Шаблон:Doc&namespace=10&hideredirs=1&hidelinks=1&limit=500 список задокументированных шаблонов], [[:Категория:Шаблоны:Документация\|категория документаций шаблонов]].		См. [http://ru.wikipedia.org/w/index.php?title=Служебная:WhatLinksHere/Шаблон:Doc&namespace=10&hideredirs=1&hidelinks=1&limit=500 список задокументированных шаблонов], [[:Категория:Шаблоны:Документация\|категория документаций шаблонов]].
Строка 34:		Строка 34:
	* В шаблонах, предназначенных для обычных редакторов, шаблон и его параметры предпочтительно называть на русском языке (хотя у латиницы есть тот плюс, что не приходится переключать раскладку клавиатуры при вводе названия шаблона{{Sp/}}его параметров).		* В шаблонах, предназначенных для обычных редакторов, шаблон и его параметры предпочтительно называть на русском языке (хотя у латиницы есть тот плюс, что не приходится переключать раскладку клавиатуры при вводе названия шаблона{{Sp/}}его параметров).
	* Есть несколько способов представить код примера использования шаблона (или его синтаксиса) в документации. Это:		* Есть несколько способов представить код примера использования шаблона (или его синтаксиса) в документации. Это:
	** тег {{Tago\|pre}}, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, поэтому, если разметка необходима, нужно либо, вместо использования {{Tago\|pre}}, начинать каждую строку примера с пробела, либо использовать шаблон {{Tl\|tpre}} (это удобно для однострочных шаблонов).{{Pb		** тег {{Tago\|pre}}, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, поэтому, если разметка необходима, нужно либо, вместо использования {{Tago\|pre}}, начинать каждую строку примера с пробела, либо использовать шаблон {{Tl\|tpre}} (это удобно для однострочных шаблонов).{{Абзац
	}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|tpre}}:{{tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}		}}Чтобы подсветить код шаблона внутри длинного кода, используйте шаблон {{Tl\|highlight}} или {{Tl\|oncolor}} (так сделано, например, в документациях шаблонов {{Tl\|переход}} и {{Tl\|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью {{Tl\|tpre}}:{{tpre\|[[t:перенесено с\|перенесено с]]\|''Вики-страница''{{Optp\|''подпись и/или текст в конце''\|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}
	** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Pb		** комбинация тегов {{tago\|code}} и {{tago\|nowiki}}, создающая маленькие поля вокруг кода.{{Абзац
	}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{pb		}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code><nowiki></nowiki></code></nowiki></code>, можно воспользоваться шаблоном {{Tl\|tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров включения шаблона рядом с кодами включения можно использовать шаблон {{Tl\|пример}} и аналогичные (в том числе {{Tl\|стопка примеров}}, {{Tl\|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{Абзац
	}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|tc}}:{{pb		}}Пример синтаксиса шаблона, оформленного с помощью {{Tl\|tc}}:{{Абзац
	}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}		}}{{Tcl\|переход\|''название раздела или якоря''{{Optp\|''тип значка''\|''название раздела''}}}}{{^\|1em}}
	* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{Tl\|флаг}}, а можно представить единой записью, как в документации шаблона {{Tl\|перенесено с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте ''представление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке {{ссылка на раздел\|Шаблон:Tc#В оформлении документации}}.		* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{Tl\|флаг}}, а можно представить единой записью, как в документации шаблона {{Tl\|перенесено с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). При этом не путайте ''представление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен по ссылке {{ссылка на раздел\|Шаблон:Tc#В оформлении документации}}.
	* Для описания параметров (полей) крупных шаблонов, кроме списков{{sp/}}таблиц, можно пользоваться хорошо оформленным шаблоном {{Tl\|описание шаблона}} (как это будет выглядеть, см. [[Шаблон:Публикация#Поля\|здесь]]).		* Для описания параметров (полей) крупных шаблонов, кроме списков{{sp/}}таблиц, можно пользоваться хорошо оформленным шаблоном {{Tl\|описание шаблона}} (как это будет выглядеть, см. [[Шаблон:Публикация#Поля\|здесь]]).
	* Для упоминания шаблонов используйте шаблон {{Tl\|t}}: {{~~пример~~\|t\|~~пример~~}}.		* Для упоминания шаблонов используйте шаблон {{Tl\|Tl}}: {{Пример\|Tl\|Пример}}.
	* Названия параметров обычно записываются со строчной буквы, при необходимости в них используются пробелы. Что касается названий самих шаблонов — дело вкуса, но вряд ли названия узкоспециальных шаблонов технического характера (как то: {{Tl\|~~lang~~-en}}, {{Tl\|Примечания}}) стоит писать с прописной. В то же время в названиях шаблонов-карточек (как то: {{Tl\|Персона}}, {{Tl\|Фильм}}) устоялась первая прописная.		* Названия параметров обычно записываются со строчной буквы, при необходимости в них используются пробелы. Что касается названий самих шаблонов — дело вкуса, но вряд ли названия узкоспециальных шаблонов технического характера (как то: {{Tl\|Lang-en}}, {{Tl\|Примечания}}) стоит писать с прописной. В то же время в названиях шаблонов-карточек (как то: {{Tl\|Персона}}, {{Tl\|Фильм}}) устоялась первая прописная.
	* Ещё одна мелочь — как в коде включения многострочных шаблонов отбивать вертикальные черты от начала строк, а названия параметров — от вертикальных черт. В английском разделе часто либо нет отбития вовсе, либо отбиваются названия параметров от вертикальных черт на один символ. У нас в этом деле разнобой.{{pb		* Ещё одна мелочь — как в коде включения многострочных шаблонов отбивать вертикальные черты от начала строк, а названия параметров — от вертикальных черт. В английском разделе часто либо нет отбития вовсе, либо отбиваются названия параметров от вертикальных черт на один символ. У нас в этом деле разнобой.{{Абзац
	}}В свою очередь, в длинных однострочных шаблонах для лучшей читаемости целесообразно отбивать каждый следующий параметр пробелом, как в шаблоне {{Tl\|~~cite~~ web}}: {{tc\|<nowiki>cite web \|url= \|title= \|author= \|date= \|work= \|publisher= \|accessdate=2016-01-27 \|lang= </nowiki>}}.		}}В свою очередь, в длинных однострочных шаблонах для лучшей читаемости целесообразно отбивать каждый следующий параметр пробелом, как в шаблоне {{Tl\|Cite web}}: {{Tc\|<nowiki>cite web \|url= \|title= \|author= \|date= \|work= \|publisher= \|accessdate=2016-01-27 \|lang= </nowiki>}}.

	== См. также ==		== См. также ==