Клуб API Карт

Улучшение Документации

Пост в архиве.
mcronni
26 января 2009, 14:25

Коллеги! Команда API Яндекс.Карт просит вашей помощи.

Мы хотим улучшить Документацию API Яндекс.Карт

Расскажите, пожалуйста:

- какие разделы вам непонятны?

- каких разделов не хватает?

- есть ли у вас пожелания по примерам?

Ответов на какие вопросы вы не нашли в Вопросах и ответах?

Нам важно ваше мнение, вне зависимости от вашего опыта программирования!

P.S.

Если у вас есть вопрос или предложение на любую другую тему, то пишите, мы будем рады ответить!

10 комментариев
Именно в "Руководстве разработчика" нету примеров со всплывающими подсказками. По классам и методам: в некоторых местах не хватает примеров, чтобы сразу понять как это можно использовать. Можно даже просто текстовые примеры, без варианта "Посмотреть в браузере". Пока все что на ум пришло. Потом если вспомню, еще добавлю
А не могли бы Вы уточнить в каких местах не хватает примеров?
Ну вот к примеру у функции setOptions(). Пока Вы мне подсказали, я не понял, как конкретно эта функция может мне помочь в отключении опции draggable. Ну и документация по YMapsML на мой взгляд несколько сумбурно выглядит: на тебя вываливается куча информации, в которую приходится структурировать в голове. Вроде бы и все наглядно нарисовано, описано, но почему-то остается ощущение некого хауса. Я не знаю почему. Может это только у меня так. Про нехватку примеров - почти на каждый класс их недостаточно, как мне кажется. Взять хотя бы http://api.yandex.ru/maps/jsapi/doc/ref/reference/map.xml Думаю, что под описанием каждого метода можно сделать одну-две строчки примера его использования. Даже если и не под каждым, то хотя бы один обобщающий пример для однотипных методов: например для событий сделать один общий пример, где можно увидеть, как можно их использовать. Я знаю, что в разделе "примеры" есть примеры на эту тему. Но когда начинаешь читать документацию, о примерах забываешь. Думаю, можно поставить перекрестные ссылки со страницы описания методов и событий на данные примеры. Думаю, что начинающих разработчиков, желающих установить карту на своем сайте предостаточно, однако им просто не хватит их знаний для самостоятельного разбора документации по всем пунктам. Еще впомнил: Мне для собственной разработки был бы очень интересен пример с несколькими слоями с метками на карте, чтобы внешними кнопками их можно было бы переключать. Т.е. на одном слое стоят одни метки, а на втором - другие. И при нажатии кнопок один из них отключается, а второй включается. И, как опцию, может даже с переключением по городам по нажатию на кнопки. Я все эти функции реализовал самостоятельно, однако, мне кажется, что не каждый дойдет до этого сам. И, наверное, стоит все-таки делать примеры более приближенными к реальным реализациям на сайтах, т.е. которы можно передалать под свои нужды минимальными усилиями. Я понимаю, что все не предусмотреть, но наиболее рапространенные вещи думаю сделать стоит.
Стоит подумать над одностраничной версией документации - было б удобней искать. Тёмная сторона документации и API - это пользовательские стили. Как поменять иконку метки я понял только из примера. Как поменять стиль иконки с текстом - непонятно. Плохо что нельзя создать свой стиль для балуна.
Раздел Пользовательские значки для меток по Вашему мнению плохо описан? Чтобы поменять стиль иконки с текстом, необходимо создать свой шаблон. О создании собственных шаблонов описано в разделе Пользовательские шаблоны. Что еще на Ваш взгляд нужно добавить в документацию?
Ну не вопрос, после того как вы конкретно указали что иконки с контентом создаются с помощью шаблонов, я сразу всё понял. Информация про то как застайлить метку не совсем очевидно разнесена по подразделам. На мой взгляд нужно добавить перекрёстные ссылки. Например: (http://api.yandex.ru/maps/jsapi/doc/dg/concepts/markers_iconcontent.xml) При создании своего собственного значка вы должны сами предусмотреть возможность растягивания значки в зависимости от его содержимого. Сделать это можно с помощью "Пользовательских шаблонов" (и ссылка). Ну и было б очевидным предусмотреть возможность определить шаблоны для балунов.
Про переопределение стиля балуна - присоединяюсь. Сам решил это просто переопределением css балуна. Но это не лучший вариант.
Думаю хорошо бы было сделать один большой пример с использованием максимального количества функций - на примере проще всего разбиратся, это бы уменьшило количество возникающих вопросов
Если использовать в одном примере большую часть функций, то начинающий пользователь API запутается. Вы так не думаете?
Ну уже есть готовы примеры попроще, я не предлагаю их удалять