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

Новый способ документирования

Описание размещено на технический форум. Предлагаю обсуждать там, чтобы не было дублирования. — doublep 23:59, 5 декабря 2006 (UTC)

Документирование в обсуждении

Что-то мне не понятно, почему в обсуждении надо викифицировать. Чем плохо так: {{Обратите внимание}}, {{linkless}}, {{Занял для работы}}? А в идеале так, как сделано в {{неоднозначность}} (см. исходный код). Mashiah 08:24, 12 марта 2007 (UTC)

Избыточность Шаблон:Template navigation

Мне кажется крайне неудачной реализация этого шаблона:

• ссылки «Шаблон» и «Обсуждение» уже есть сверху, это бесполезное дублирование
• ссылка «Документация» ведёт на страницу, которая уже включена в страницу шаблона, и это очень сильно сбивает с толку. Когда кликаешь по ссылке, ожидаешь, что там будет дополнительная документация
• ссылка «Где используется» тоже дублирует имеющуюся слева «Ссылки сюда», можно конечно сказать, что некоторые новички об этом не знают, но таких по-моему мало

В общем, я предлагаю этот шаблон не использовать, тем более что Kalan уже встроил в {{doc}} внятные и действительно нужные ссылки [править] [история] [обновить] ∴ Alex Smotrov 22:55, 29 мая 2007 (UTC)

В принципе, я не против. Пожалуй, этот шаблон действительно уже избыточен. Просто он не был таким пока {{doc}} был попроще. — doublep 17:03, 30 мая 2007 (UTC)

Да, конечно. Нужно просто пройти ботом и отовсюду его убрать, а шаблон удалить. --Kaganer 16:55, 14 июля 2007 (UTC)

Выставил на удаление через ВП:КУ - Википедия:К удалению/1 июля 2008#Шаблон:Template navigation. Alex Spade 18:44, 2 июля 2008 (UTC)

Новые шаблоны из en-wiki

Анонимный участник 75.138.68.170 перенёс к нам несколько анг. шаблонов документирования: {{Pp-template}}, {{Template doc inline}} и {{Template doc}}. Нужно бы как-нибудь их "переварить" (либо включить в нашу систему, либо как-то ещё). --Kaganer 22:31, 21 июля 2007 (UTC)

Созданы перенаправления:

• {{Pp-template}} → {{Protected template}}
• {{Template doc}} → {{Doc}}

Третий шаблон пока вне системы. ~ putnik 18:08, 17 декабря 2007 (UTC)

Обновление стандартов

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

Предлагаю следущее:

1. Полностью добиваем {{ДШ}} (я это сделаю в течение пары дней) — Сделано
   • Удаляем его — Сделано
2. Убираем из рекомендованных шаблонов {{template navigation}} — Сделано
   • Со страниц шаблонов он должен постепенно удаляться
   • Возможно, его стоит оставить на странице документации
3. Делаем меташаблон-сообщение {{Совместимость документации}} (или как-нибудь так) на основе {{ambox}} — Сделано
   1. Заменяем использование всех шаблонов, созданных для совместимости, на {{doc}}
   2. Перенаправляем их на меташаблон
4. Оставляем рекмендуемым шаблоном только {{doc}}, и переписываем в соответствии с этим общие рекомендации — Сделано

Всех устраивает? Может есть какие предложения? ~ putnik 15:43, 15 октября 2007 (UTC)

Я согласен. {{template navigation}}, разумеется, должен быть только на стр. документации. Но там он нужен, в обёртке из "noinclude"--Kaganer 17:42, 16 октября 2007 (UTC)

Хм. у меня тут возникло ещё одно предложение. Есть вариант создать шаблон для страницы документации, тогда 1) не будет путаницы, куда его можно вешать. Всегда можно будет централизованно его изменить, не думая, что это повлияет. Сейчас для этого посути надо только ботом пройтись по всем страницам документации и поменять {{template navigation}} на него. ~ putnik 12:55, 21 октября 2007 (UTC)

Объединение документации группы близких шаблонов

С технического форума: «во-вторых, начать избавляться от старой системы документирования шаблонов с отдельными подстраницами (которая IMHO сыграла свою роль, но не отвечает современным требованиям), и переделать их в сборные страницы документации по группам шаблонов — имеется не так уж много шаблонов, которые настолько сложны в использовании, что требуют для описания отдельную страницу». — Incnis Mrsi.

Мне кажется, это здравая идея. Только я предлагаю не избавляться от старой системы, а улучшить её. В шаблон {{doc}} можно добавить необязательный параметр. Он будет включать подстраницу /Документация текущего шаблона или шаблона, указанного первым параметром. То есть, например, Шаблон:foo2 может использовать код {{doc|foo}}. — doublep 12:10, 21 октября 2007 (UTC)

Косметическое изменение. Я предлагаю полностью переориентироваться с подстраниц в пр-ве «Шаблон:» на списки наподобие Википедия:Шаблоны/Ссылки для внутреннего использования — к чему загонять их в подстраницы каких-то конкретных шаблонов? Да и ссылка на документацию из шаблона должна ссылаться прямо на раздел (с якорем). Incnis Mrsi 12:38, 21 октября 2007 (UTC)

Ну доп. параметр можно и ввести, хотя это чистая косметика. Потому что можно использовать (и они используются) перенаправления на чужую документацию. А {{doc}} на данный момент лучшая система оформления документации. ~ putnik 12:46, 21 октября 2007 (UTC)

Лучшая или нет, но {{doc}} поощряет создание многочисленных разрозненных страниц. Товарищи документаторы IMHO не понимают одну важную вещь: не столь важно объяснить как пользоваться шаблоном (что там объяснять-то? в 80% случаев просто параметры перечислить), сколь что им надо пользоваться. А для документирования какой-то системной практики применения шаблонов все эти «/Документация» бесполезны. Incnis Mrsi 16:47, 21 октября 2007 (UTC)

Так, я потерял нить обсуждения. Вариант документирования через {{doc}} с параметром, дающим возможность создавать одну страницу документации для нескольких шаблонов, на данный момент всех устроит? ~ putnik 18:06, 21 октября 2007 (UTC)

Насколько я понял, здесь два момента. Один — это связь между шаблоном и его документацией; эта проблема решается {{doc}}: документация шаблона есть прямо на его странице. Второй — связь между документацией различных шаблонов. Особенно в том плане, чтобы объяснять не как использовать шаблон Foo, а как сделать X: использовать шаблоны Foo, Bar и/или Baz. По-моему, всё же лучше не отказываться от {{doc}}, а совмещать обе системы. Лучше, пожалуй, сделать параметр, напрямую указывающий страницу документации. Это некритично, но позволит задавать осмысленные имена для страниц. Например Википедия:Шаблоны/Сепуление, а в шаблонах {{Сепуледром}}, {{Сепулькарий}} и {{Сепулятор}} писать {{doc|Википедия:Шаблоны/Сепуление}}. Таким образом, будет и осмысленно названная общая страница документации по группе шаблонов, и каждый шаблон будет иметь документацию прямо на своей странице, с бонусом в виде документации по родственным шаблонам. Плюс для сложных шаблонов типа {{НП}} имеет смысл сохранять выделленную страницу документации. — doublep 19:10, 21 октября 2007 (UTC)

Разумная переделка, буду оказывать всяческое содействие. Incnis Mrsi 13:07, 22 октября 2007 (UTC)

Параметр добавлен, теперь можно писать {{doc|Википедия:Шаблоны/Сепуление}}. Шаг сделан, дальше будем думать. ~ putnik 13:45, 22 октября 2007 (UTC)

Предлагаю начать с проставления нового {{doc}} там, где не успели создать подстраницу. Можно пройтись, в частности, по красным Док-ссылкам на Википедия:Шаблоны/Ссылки для внутреннего использования и вписать в нужные шаблоны ссылки на эту страницу. Боюсь, что у меня не везде хватит для этого привилегий. Incnis Mrsi 14:42, 22 октября 2007 (UTC)

Тааааак… а можно сделать к {{doc}} ключик чтобы выключать дурацкое включение страницы, и давать только ссылки? Или делать под это новый шаблон? Я что-то сходу не разобрался в том, что вы тут сотворили. Incnis Mrsi 14:48, 22 октября 2007 (UTC)

Ещё раз, пожалуйста. Зачем ссылки? Предполагается, что документация даётся сразу на странице. Только ушли от ужаса с {{ДШ}}, который отправлял на страницу обсуждения. Зачем создавать новый ужас? ~ putnik 05:51, 23 октября 2007 (UTC)

Главный смысл текущей схемы документации - в том, чтобы новичок (и не только) попав по ссылке на страницу шаблона мог понять, как и где его правильно использовать. Какими средствами это будет достигаться - не суть важно. Но система, предлагаемая Incnis Mrsi, эту задачу не решит. --Kaganer 22:49, 21 октября 2007 (UTC)

Создание, значит, дерева страниц документации для шаблонов Вам не нравится? Бывает, не все это любят. Привязка страниц этого дерева к страницам правил и указаний Вам тоже не по душе? Ой, что бы ещё придумать-то… Ну, создание специализированных категорий документации типа категория:Википедия:Оформление обсуждений. Нет? И навигационные шаблоны по образцу {{talk pages}} тоже не нравятся? Тогда боюсь, что Вам не угодишь никакой системой, разве что снести всю документацию к чертям ☺ Incnis Mrsi 13:07, 22 октября 2007 (UTC)

Я ничего не говорил про то, что мне что-то не нравится. Я обозначил конкретную задачу, для которой не увидел места в твоей системе. Если я что-то проглядел - покажи. Детально изучить твои предложения и высказать какие-нибудь замечания я смогу, видимо, только после конференции (кстати, если ты не читаешь рассылку, то я просил прислать мне письмо с персональными данными и указанием на то, что писать на бэйджике). --Kaganer 09:10, 23 октября 2007 (UTC)

Категория:Википедия:Шаблоны

Предлагаю вернуться к предложению участника Kaganer об убирании лишнего префикса «Википедия:» из названий категорий. Давайте хотя бы новые создаваемые категории называть нормально, а уже созданные категории перевести постепенно, при случае ∴ AlexSm 21:11, 24 октября 2007 (UTC)

Напомни pls аргументацию. На этой странице нет ничего об этом. Mashiah 23:51, 24 октября 2007 (UTC)

Предложение было тут, а аргументация ... ну какая тут может быть аргументация, если в названиях категорий просто лишнее слово? Я бы очень хотел посмотреть на аргументацию того, кто выдумал так делать. Кроме того, при категоризации самих категорий привычно пишешь [[Категория:...|{{PAGENAME}}]], и из-за этого лишнего слова получается в корневой категории Категория:Википедия:Шаблоны куча категорий на букву «В». Единственное возможное достоинство — это список сразу всех категорий шаблонов на Special:Prefixindex/Категория:Википедия:Шаблоны, однако поскольку некоторые категории уже без «:Википедия:», то это уже не работает. В общем, лично я буду создавать категории шаблонов с нормальными названиями, но вот как бы этому научить других участников, стандартно создающих категории по существующим примерам ... ∴ AlexSm 19:11, 25 октября 2007 (UTC)

Предлагаю этим префиксом выделять шаблоны, используемые в пространстве Википедия:. infovarius 13:46, 22 апреля 2009 (UTC)

{{doc}} — маленькое предложение

Переименовать бы {{Doc}} в {{Документация}} или другое русское название. Saproj 06:43, 22 ноября 2007 (UTC)

Нафиг такие предложения. И без того полно разнобоя и неразберихи с шаблонами. Раз, созданный мною шаблон переименовали, а страничку документации — забыли. И документация перестала отображаться. Уж если то что сейчас существует, хоть как-то работает, то давайте не делать косметических изменений! Incnis Mrsi 11:23, 23 ноября 2007 (UTC)

Зачем?? {{doc}} используют исключительно авторы шаблонов. Неужели doc для них так страшно, непонятно и неудобно? --Maryanna Nesina (mar) 11:37, 23 ноября 2007 (UTC)

Лично мне бы хотелось немножко наоборот, чтобы в шаблоне использовалась простая и короткая подстраница \doc, а не \Документация ∴ AlexSm 15:11, 23 ноября 2007 (UTC)

Вот и мне тоже :) --Maryanna Nesina (mar) 16:34, 23 ноября 2007 (UTC)

Это да. Но в текущей ситуации я лично за то, чтобы всё осталось, как есть. незачем воду мутить. ~ putnik 17:19, 23 ноября 2007 (UTC)

Ну он может включать /doc если есть, иначе /Документация. Хотя это несколько шизофренично, не знаю, насколько это будет (если будет) сбивать с толку. — doublep 17:36, 23 ноября 2007 (UTC)

includeonly

Не совсем понимаю, почему в русском разделе ставят интервики и категории на основную страницу шаблона в тег «noinclude», а не на подстраницу документации в тег «includeonly», как, например, в английском разделе. По-моему, если интервики и категории будут находиться на подстранице документации, то это снизит нагрузку на сервер при их добавлении вручную, а также уменьшит число запросов на редактирование защищённых страниц. — redmond barry 01:54, 8 декабря 2007 (UTC)

Никаких подстраниц документации в тег «includeonly» не бывает. Интервики и документация всегда располагаются только в noinclude, учите матчасть. Incnis Mrsi 10:02, 8 декабря 2007 (UTC) Не так понял мысль. Incnis Mrsi 10:30, 8 декабря 2007 (UTC)

Если страница документации уже есть, то пожалуй лучше интервики и категорию перемещать туда. —AlexSm 03:14, 25 мая 2008 (UTC)

К сожалению, для любых автоматических правок это неудобоваримо. А боты при этом вообще часто глючат. infovarius 13:47, 22 апреля 2009 (UTC)

Когда {doc} лишний

На странице шаблона {{doc}} написано: «Основная цель выноса документации на отдельную страницу — избежать перегенерации HTML для всех страниц, использующих шаблон, при редактировании его документации». Лично я с этим согласен. Вопрос: для чего выносить документацию на отдельную подстраницу у Шаблон:Игры Blizzard Entertainment с менее чем 20 включениями? —AlexSm 03:14, 25 мая 2008 (UTC)

А не пофиг ли, будет у шаблона одна страница с длинным <noinclude> или две страницы с трансклюзией? Incnis Mrsi 12:04, 25 мая 2008 (UTC)

Шаблон Карточка компании

обсуждение заполнения Pessimist2006 14:58, 2 января 2009 (UTC)

• формулировка. Предлагаю поддержать. --Pessimist2006 07:51, 13 марта 2009 (UTC)

Шаблон:Подстраница документации

Нужен ли этот шаблон (видимо, калька с английского)? Единственный интерес - показывает разные вещи в шаблоне и в его документации. infovarius 10:56, 24 марта 2009 (UTC)

• Шаблон сейчас удаляется--WindEwriX 10:03, 14 августа 2009 (UTC)
• Я переименовал в это название используемый шаблон {{Docpage}} (он же {{Template navigation}}). --Kaganer 14:02, 28 января 2010 (UTC)

Подстраницы для песочницы и тестирования шаблонов

При разработке нового шаблона изучал методы зарубежных коллег. Шаблон был непростой, поэтому требовалось организовать его тестирование должным образом. Обнаружил весьма интересный подход, основанный на создании подстраницы песочницы и связанной с ней подстраницей тестов и описываемый на Wikipedia:Template sandbox and test cases. Применил этот подход на шаблоне {{HumanizeDate}}, заодно сделав перевод упомянутой страницы (Википедия:Правка и тестирование шаблонов в песочнице), сопутствующих шаблонов ({{песочница шаблона}} и {{тесты шаблона}}), дополнив шаблон документации {{doc}} нижним колонтитулом, а также разработав свой шаблон, {{TestCase}}, для тестирование шаблонов-функций. Пример использования последнего можно посмотреть на странице тестов шаблона {{HumanizeDate}} — Шаблон:HumanizeDate/тесты.

Вероятно, несколько поторопился с изменением шаблона {{doc}}, потому как моё изменение было отклонено с формулировкой «не стоит засорять ПИ шаблонов». Честно говоря, не считаю, что добавление двух подстраниц с регламентированным названием можно считать засорением пространства имён. В конце концов, все страницы равны перед движком Википедии, в каком бы пространстве имён они ни находились.

Что думаете об этом подходе? —Volgar 16:33, 29 декабря 2010 (UTC)

Вообще идея интересная. Думаю, надо попробовать использовать тесты в разных шаблонах, и, если приживётся, добавлять в центральные шаблоны. infovarius 08:05, 13 января 2011 (UTC)

Идея не просто интересная, она нужная. Для пользователей, которые никогда не редактировали шаблоны (вроде меня), не совсем понятно как тестировать шаблон. А если есть готовые ссылки, то всё гораздо проще. Жаль, что изменение откатили, но там вроде бы была просто проблема с правильным оформлением. Кто-нибудь, пожалуйста, доведите дело таки до конца. Akela1101 12:21, 30 декабря 2014 (UTC)

Прошу оценить документацию

Речь идёт о замечательном шаблоне {{arf}}, созданном участником Azgar. Первоначальную версию документации я подверг критике за, на мой взгляд, малую читабельность. Как вы считаете, был ли я прав в тот момент? Потому что другие участинки высказывали удивление такой оценкой. Тем не менее, документация была переработана, и результат меня более чем устраивает. В связи с этим прошу участников проекта его оценить, а также сравнить с лучшими образцами документации. В случае, если сравнение окажется в его пользу, то предлагаю принять документацию этого шаблона за эталон. С уважением, Илья_→^← 16:05, 1 апреля 2012 (UTC)

• Судя по всему, проект более мёртв, чем жив. --Azgar 11:05, 5 апреля 2012 (UTC)
  • Ну, не стоит судить так. Просто я не мог ответить Вам тогда, когда прочёл Ваше сообщение, а сейчас Вы напомнили. У нас нет каких-либо эталонов, каждый пишет документацию по своему усмотрению. Мне тоже новый вариант нравится более старого. KPu3uC B Poccuu 11:12, 5 апреля 2012 (UTC)

Шаблон для отражения научных дискуссий

Коллеги, у меня возник следующий вопрос. Существует ли шаблон для отражения в составе статей дискуссий, которые ведутся в научном сообществе по той или иной теме. Думаю, наличие такого шаблона позволило бы избежать многих конфликтных ситуаций при редактировании статей Википедии. Результат использования такого шаблона (если он существует или будет создан) может выглядеть примерно так:

Тема дискуссии

Научная позиция № 1	Научная позиция № 2
Представители позиции № 1	Представители позиции № 2
Аргументы за позицию № 1	Аргументы за позицию № 2

Подчеркиваю, что данный шаблон должен быть применим именно к объективно существующим дискуссиям в научном сообществе, а не к необоснованным разногласиям участников. Можете ли Вы дать пояснения по этому вопросу? -- АлександрЛаптев 20:24, 11 июня 2012 (UTC)

Обязательное использование TemplateData

Я считаю, что технический прогресс уже достиг таких масштабов, чтобы на каждой странице с документацией нужно было использовать TemplateData. Данный способ описания параметров шаблона мне кажется приемлемым, нежели создание разделов «параметры шаблона» или вообще отсутствие описания параметров. Коллега википедист Oleg3280 (обс. · вклад) считает, что использование данной технологии необходимо только в случае, если такая технология будет использоваться всеми и вся (правка 84503946). Прелести технологии описаны на странице mediawikiwiki:Help:TemplateData/ru. — Dimon4ezzz ^(обс.) 19:06, 26 марта 2017 (UTC)

Ко всему прочему, хотел бы заметить, что использование такого способа приведёт к унификации (стандартизации) Викиепедии, как использование шаблонов — Dimon4ezzz ^(обс.) 19:10, 26 марта 2017 (UTC)

• Народ обычно возражает, что машинночитаемые данные не могут заменить человеческое описание параметров, и я склонен согласиться. Рандомное в тему: вот 7 шаблонов, где зачем-то templatedata в шаблоне, хотя есть подстраница /doc. — Джек, который построил дом (обс.) 07:16, 27 марта 2017 (UTC)

Википедия:Документация шаблонов

Цель этой страницы? Даже нет категорий и практически нет внешних ссылок. Перенести в этот Проект? Предложить к удалению? Или сделать эссе на тему, как в англовики? Oleg3280 (обс.) 14:27, 31 марта 2017 (UTC)

pre: «начинать *первую* строку примера с пробела»

Джек, по поводу формулировки, вызвавшей сомнение. Приведу два живых примера.

Во-первых, «Образцы для копирования» в документации {{cite web}}. Обрати внимание, что закрывающие фигурные скобки в многострочных вариантах пробелом не отбиты (в т. ч. и в исходнике), так что это уже не «каждая» строка.

Другой пример, аналогичные образцы. Пробелом в исходнике отбита только первая строка (которая <nowiki>), и весь следующий абзац отображается через <pre>.

Так кто же прав? Всё-таки «начинать первую строку примера с пробела», а не «каждую». Есть контраргументы или вернём «первую»? — Mike Novikoff 14:50, 6 августа 2017 (UTC)

• Так это работает, только если сразу идёт <nowiki>, а на этой странице речь про ситуацию, когда «разметка необходима». То есть, например,

   {{((}}main
    |''Статья 1''
    |''Статья 2''
    |l1=''Отображаемый текст ссылки 1''
    |l2=''Отображаемый текст ссылки 2''
   }}

  ↓

{{main
 |Статья 1
 |Статья 2
 |l1=Отображаемый текст ссылки 1
 |l2=Отображаемый текст ссылки 2
}}

— Джек, который построил дом (обс.) 15:15, 6 августа 2017 (UTC)

• Да, про «разметка необходима» я недоглядел. — Mike Novikoff 15:35, 6 августа 2017 (UTC)