Обсуждение шаблона:Doc

Обсуждение необходимости шаблона

(Добавлено позже: речь шла о {{template navigation}} —AlexSm 16:30, 5 мая 2008 (UTC)

Мне кажется неудачной сама идея такого шаблона.

1. Бесполезное дублирование ссылок «Шаблон · Документация · Обсуждение · Использование»:
   • «Шаблон» и «Обсуждение» просто есть сверху чуть-чуть выше
   • Про «Ссылки сюда» слева не знают только новички
   • «Документация» ведёт на страницу, которая уже включена в страницу шаблона, и это очень сильно сбивает с толку.
2. В чём вообще заключается смысл выделения документации на отдельную страницу?
3. Кстати, можно посмотреть на аналогичный шаблон в Википедиях на других языках?

— Alex Smotrov 17:25, 10 февраля 2007 (UTC)

en:Template:Documentation. — redmond barry — Реплика добавлена в 23:35, 16 октября 2007 (UTC)

Мой вопрос скорее относился к {{template navigation}}, в тот момент я воспринял его как часть {{doc}}. С тех пор выяснилось, что и для {{template navigation}} есть место в жизни, но только исключительно на подстранице документации в виде <noinclude>{{template navigation}}</noinclude> ∴ AlexSm 02:58, 17 октября 2007 (UTC)

Всплывающие подсказки

По поводу ссылок [просмотр] [править] [история] [обновить]

Я думаю, что для этих ссылок нужны всплывающие подсказки в виде пояснений.
Например:

• для ссылки [просмотр] всплывающей подсказкой может быть «Перейти на подстраницу документации»;
• для ссылки [править] — «Редактировать подстраницу документации»;
• для ссылки [история] — «Просмотр истории редактирования подстраницы документации»;

А, вот, назначение ссылки [обновить] мне не совсем ясно, что, собственно, и подвигло меня предложить идею с подсказками.
Если не ошибаюсь, для этого надо заключить ссылки в тег <span title="НУЖНЫЙ_ТЕКСТ">...</span>. — redmond barry, 5 мая 2008

Если это реализуемо для ссылок (у которых свой tooltip), то прошу пример в студию. —AlexSm 16:30, 5 мая 2008 (UTC)

Я сделал рабочий пример - шаблон:Doc1: подсказки - всплывают, и "imagemap" работает. Правда есть пара недостатков: первый - "imagemap" добавляет перенос строки, и с этим, видимо, можно бороться только введением дополнительной невидимой таблицы. Второй (как мне кажется, несущественный) я где-то там что-то пропустил в стилевом оформлении. --redmond barry 04:56, 12 мая 2008 (UTC)

Шаблон:Template doc begin

Ещё предлагаю сделать логотип ссылкой на подстраницу документации:

<imagemap>
    Image:Information.svg|20px
    default [[{{FULLPAGENAME}}/Документация|Документация]]
    desc none
</imagemap>

Думаю, это будет лучше, чем ссылка в никуда. — redmond barry, 5 мая 2008

Можно. Лично я бы при этом справа вообще убрал все ссылки кроме «стандартной» [править], потому что полезность [просмотр] [история] и [обновить] вызывает у меня большие сомнения. —AlexSm 16:30, 5 мая 2008 (UTC)

Шаблон:Template navigation

Кстати, предлагаю убрать {{template navigation}} с главной страницы шаблона: он же ведь только для подстраниц документации. — redmond barry, 5 мая 2008

Согласен, это надо убрать. —AlexSm 16:30, 5 мая 2008 (UTC)

Вместе с категориями и интервики переместил на подстраницу документции (ещё вчера). --redmond barry 05:18, 14 мая 2008 (UTC)

Иллюстрация в начале документации

В целях улучшения внешнего вида страниц документации шаблонов предлагаю заменить иллюстрацию из верхней части страницы страницы с на . Этим достигается сразу несколько целей:

1. Новый значок более подходит по смыслу на странице документации, подчеркивая, что это именно страница документации щаблона, а не просто какая-то абстрактная информационная страница.
2. Интерфейс русской википедии станет более унифицированным с интерфейсом других, более развитых, языковых разделов (например, английского и французского).
3. Сразу хочу дать ответ на возражение участника Cantor (O) (расположенное здесь:

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

Думаю, что "режет глаз" - это очень субъективная оценка, поэтому с ней трудно работать. Но отмечу, что основной текст документации шаблона тоже находится на голубом фоне, который сглаживает контраст между страницей и значком (вот если бы фон был, например, зеленоватым, как в en.wiki, то было бы хуже, но такого я и не предлагаю). — Эта реплика добавлена участником Sergey Liverko (о • в) 10:19, 23 января 2010 (UTC)

Чтобы участники могли оценить, как будет выглядеть результат, приведу пример документации к самому шаблону {{doc}} в новом формате:

__NOEDITSECTION__

 Документация

---

Включает подстраницу с документаций для текущего шаблона. Точнее, включает шаблон название страницы/doc. Работает также и в обсуждении шаблона, то есть включает одну и ту же страницу как из шаблона, так и из его обсуждения. И всё же включение документации в обсуждение является нежелательным.

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

Документация шаблона {{doc}} сформирована по тому же принципу, так что можно посмотреть код.

Основная цель выноса документации на отдельную страницу — избежать перегенерации HTML для всех страниц, использующих шаблон, при редактировании его документации. Также это сокращает страницу самого шаблона, что делает редактирование проще.

Шаблон поддерживает необязательный параметр. При вводе {{doc|Полное название страницы}} вместо страницы /doc будет включена любая необходимая. Это удобно для создания общей документации для однотипных шаблонов.

См. также проект по документированию шаблонов.

— Эта реплика добавлена участником Sergey Liverko (о • в)

Мне новый вариант кажется слишком грубым, тёмным. Точнее сказать, к сожалению, не могу. — Vort 10:42, 23 января 2010 (UTC)

• Согласен с аргументацией участника Cantor, к чему такое крупное броское изображение? Хотя против внешнего вида я ничего не имею, было бы голосование, я б проголосовал за нынешний вариант.--Letzte*Spieler 11:53, 23 января 2010 (UTC)
  • Я немного подредактировал пример - уменьшил на треть изображение и убрал жирное начертание у слова "Документация". Теперь стало лучше?
    • Опять же моё личное мнение — стало лучше первоначально предложенного, но по-прежнему хуже того что используется сейчас. — Vort 12:09, 23 января 2010 (UTC)
• Подредактировал исходный вариант, осветлив его. Смотрим :) Предлагаю всё же не сдаваться и довести новый вариант до ума. Sergey Liverko 12:58, 23 января 2010 (UTC)
  • Немного поясню по поводу цвета. Исходный вариант по цветовой гамме хорошо согласуется с остальными элементами дизайна в Википедии (как минимум в бета-интерфейсе) (цвет фона документации, цвет её рамки, фона страницы и ссылок). Поэтому что-то сильно выделяющееся отвлекает внимание пользователя, что в данном случае делать не стоит — так как главное тут не картинка, а текст. Хотелось бы услышать мнения других участников, ближе знакомых с дизайном. — Vort 13:06, 23 января 2010 (UTC)
    • Действительно, хотелось бы, но поскольку таких участников может и не прийти, думаю, что на данном этапе надо выработать консенсус хотя бы в нашем текущем составе. Во-первых, без этого все равно не обойтись (финальный вариант должен устроить всех), во -вторых, не исключено, что другим участникам не принципиально, какой вариант будет в итоге принят. Как я понял, под "Исходным вариантом" вы понимаете ту картинку, которая стоит сейчас, т.е. . Действительно, он подходит под дизайн бета-версии (я сам в ней работаю), но я постарался привести к этому дизайну и предлагаемый мною вариант, убрав цветовую насыщенность. Если дело только в цвете, то его можно выставить любым - для меня принципиально содержимое значка (а фигурные скобки подчеркивают, что страница относится именно к шаблону). Sergey Liverko 17:31, 23 января 2010 (UTC)
• Может лучше будет примерно так, как это делается в шаблоне Tl: {{}} ? --Alogrin 01:41, 24 января 2010 (UTC)
  • Давайте посмотрим, что получается в Вашем варианте: Sergey Liverko 09:20, 24 января 2010 (UTC)

{{}} Документация

• Скобки сразу смотрятся "неродными", поскольку композиционно предполагаются частью значка, но визуальные стили совершенно разные. Причем обратил внимание на один зрительный недостаток текущего значка: видимо, из-за очень светлых оттенков края круга кажутся пикселизированными (ломаными). На вновь предлагаемом варианте такого не заметно. Sergey Liverko 09:20, 24 января 2010 (UTC)
• Поддерживаю. В английской ВП этот шаблон выглядит лучше. С уважением, Илья 20:20, 21 сентября 2011 (UTC)

notoc

Админы! Обратите внимание, подшаблон {{Doc/begin}} вызывается с параметром notoc, несмотря на то, что последний оттуда давно убран.—Bandar Lego 10:08, 4 февраля 2011 (UTC)

Песочница

Предлагаю добавить в нижний колонтитул текст со ссылками на песочницу и документацией по ее использованию, как в английском варианте {{documentation}}. Немного стандартизации в тестировании изменений шаблонов, на мой взгляд, не помешает. Чтобы каждому не приходилось изобретать свой "велосипед" для тестирования. --14:30, 13 сентября 2011 (UTC)

Почти год назад перевёл инструкцию и все сопутствующие шаблоны, но вот широкой поддержки у предложения не увидел. Хотя, сейчас понимаю, что идти надо было на Обсуждение проекта:Шаблоны, а не Обсуждение проекта:Документирование шаблонов.

Как вариант можно условно включать текст про песочницу в колонтитул, если песочница и тесты созданы. Но не думаю, что кто-то начнёт этим пользоваться, если об этом нигде не будет ни слова. —Volgar 07:47, 14 сентября 2011 (UTC)

Получается, что сейчас уже 3 года инструкция не соответствует шаблону. Может всё-таки поправить шаблон в соответствии с инструкцией? Akela1101 11:59, 30 декабря 2014 (UTC)

да, пора. Я За--boom1x 13:28, 13 июня 2015 (UTC)

Параметр content

Было бы неплохо добавить параметр |content = по образцу англовики:

Parameter |1 = and the |content = parameter can also be combined, like this:

<!--Last line of your template code--><noinclude>
{{Documentation |1=Template:Any page/doc
| content =
{{Template:Any page/doc |parameters}}
}}</noinclude>

Then the pagename fed as parameter 1 is used for the [edit] [purge] links and for the /doc link in the link box below the doc box. But the content parameter is used for the content shown in the doc box. The above code means that the content is transcluded as {{Template:Any page/doc|parameters}}. In this example a parameter is also fed to the /doc page being loaded.

К примеру, у меня есть общая документация для шаблонов семейства {{tr-x}} для указания перевода. Ей я хочу кормить параметры (код языка, название языка в родительном падеже, слово для примера, перевод слова для примера), что из шаблона {{doc}} сделать невозможно — можно только указать адрес страницы. Из-за этого я вынужден делать не общую документацию, а обычную для каждого шаблона и в неё вставлять код, как, например, на Шаблон:Tr-la/doc:

<noinclude>{{docpage}}</noinclude>
{{tr/doc-lang
| код языка = la
| род. п.   = латинского
| терм      = in situ
| перевод   = на месте
}}

<includeonly>[[Категория:Шаблоны языков|{{str sub|{{ROOTPAGENAME}}|3|10}}]]</includeonly>

(Даже категорию туда убрать не могу, потому что тут нужен как бы двойной инклюдонли, равно как для {{docpage}} двойной ноинклюд. Мм, хотя {{docpage}} в таком случае будет бессмыслен, ибо не будет той подстраницы, на которой он будет виден с ссылками для конкретного шаблона.) — Джек, который построил дом 21:42, 15 февраля 2016 (UTC)

Редизайн документаций

Предлагается следующее изменение оформления документаций шаблонов/модулей. Изменение было предварительно обсуждено в кругу техников проекта.

Было, стало. Причины, я полагаю, будут понятны — сейчас оформление, по сути, случайно: используются произвольные параметры шрифта, отступы, рамка, кнопки в меню не оформлены в стандартном стиле. Предлагался также вариант с меню в стандартном месте (справа от заголовка), но он предварительно не получил поддержки (как, впрочем, и явно негативных отзывов). — Джек (обс.) 14:48, 11 июня 2018 (UTC)

• Редизайн был проведён с небольшими корректировками. Между тем в чате инженеров был также предложен и поддержан такой вариант. К нему на настоящий момент склоняюсь и я, так как 1) при нынешнем варианте заголовки разделов документации визуально путаются с заголовком самой документации (например), 2) он выдержан в духе недавнего редизайна шаблона {{закрыто}}; также такая шапка используется в эдитинтро (шаблон {{бокс для эдитинтро}}). — Джек (обс.) 23:24, 23 июня 2018 (UTC)

Безымянная тема

Перенесено со страницы Обсуждение шаблона:Doc/doc.

Быть может, в документации к {{doc}} следует сразу упомянуть {{docpage}}? Или появление документации в некатегоризованных шаблонах кому-то помогает выявить несовершенство? Microzaur 15:14, 6 июля 2012 (UTC)