Обсуждение документации MQL4 - страница 8

 
Gorillych:
Всё можно понять, документация есть, примеры есть, Rosh всё написал.
Меня не устраивают только примеры в документации. Здесь на сайте столько этих примеров было уже написано, а в документации всё те же - тупые :(

Я предлагаю (кажется, уже в третий раз) в online документацию на сайте внести возможность добавления своих комментариев. Это успешно применяется в других ИТ технологиях.
Вот пример такого описания функции: базовое, плюс готовые куски кода ниже сторонних разработчиков - бери и копируй.

 
Yurixx, что конкретно в документации не так? Приведите, пожалуйста, четкие указания на ошибки и мы это исправим.

Например, была ошибка с неуказанным идентификатором и мы ее уже исправили:

Jhonny писал (а):
К стати про документацию, заметил некую странность при нажатии на F1 на свойстве OBJPROP_FIBOLEVELS в иструментарии происходит что то не то, а точней практически ничего не происходит.


Если же Вы хотите иметь максимально детализированную документацию на все случаи жизни, то этого не получится, к сожалению. Вставить аналог MSDN в терминал будет сложно. Чтобы мы не написали, все равно будут вопросы. И даже наличие статей, библиотеки кода, форума и поисковой системы по всему этому хозяйству не всегда поможет.


Тема этой ветки заставила меня ясно сформулировать давно назревшую мысль. Теоретического подхода "дайте мне хорошую документацию/книгу и я переверну мир" недостаточно. Нужна практика с обязательным и самостоятельным наступанием на грабли.

Случай из нашей практики:

Мы давно улучшаем методологию разработки софта, а также готовимся к сертификации по ISO9000. За последние пару лет закуплены десятки книг по теме, перечитано много, все согласны с необходимостью внедрения. Но теории недостаточно. Нужно браться и делать. Что мы шаг за шагом и делаем.

Трудно это - после книжек полный бардак в голове. Самое время выйти куда-нибудь и крикнуть "документация плохая". Сразу же всплывает мысль "давайте вызовем консультантов" и пусть они нам тут все сделают. Но разум подсказывает, что мы сами должны все понять и изменить, а не только прочитать водянистый отчет консультантов.

Тоже самое и в бизнесе. Если читать только книжки, то все покажется просто - "поверил в себя, встряхнулся, открыл бизнес и все поехало". В жизни все по-другому.

Наша позиция по документации:

  • заниматься интерактивным обучением трейдеров на глобальном уровне во всем мире через специальный сайт MQL4.community
  • предоставить возможность трейдерам помогать друг другу и делиться знаниями
  • дать возможность трейдерам общаться напрямую с разработчиками
  • стимулировать написание статей трейдерами, переводить их на другие языки
  • накапливать информацию в единой точке, чтобы любой мог получить к ней доступ

То есть, наша задача по обучению гораздо шире простейшей встроенной документации. Например, вчера я прилетел из Шанхая, где мы открыли наш офис, который занимается продвижением МетаТрейдера в Китае. В ближайшие месяцы будут серьезные изменения в китайской части наших сайтов.

Глядите шире, как это делаем мы.

 
chv:

Я предлагаю (кажется, уже в третий раз) в online документацию на сайте внести возможность добавления своих комментариев. Это успешно применяется в других ИТ технологиях.
Вот пример такого описания функции: базовое, плюс готовые куски кода ниже сторонних разработчиков - бери и копируй.

Да, это хорошая идея и скорее всего мы ее реализуем.

Мы продолжаем работы над MQL4 сайтом и у нас много задумок. Завтра как раз выпускаем бета-версию нового редактора для сайта. Потом будет новая версия продвинутой функции "Похожие темы".
 
Вот еще что хотел сказать, в этой теме часто посылали новичков к статьям Rosha, однако я тоже не брезгую туда иной раз заглянуть, правда давненько не заглядывал, так вот сайт то у альпари малец сменился и все ссылки от сюда 'Обзор статей Rosh'а: эксперты в MetaTrader 4' ведут на ошибку 404. Так что нужно поправить ссылки.

ЗЫ Потом то конечно я увидел коментарии, но статья нужная мне была 6 почти самый верх, поэтому заметил не сразу.
 
Jhonny:
Вот еще что хотел сказать, в этой теме часто посылали новичков к статьям Rosha, однако я тоже не брезгую туда иной раз заглянуть, правда давненько не заглядывал, так вот сайт то у альпари малец сменился и все ссылки от сюда 'Обзор статей Rosh'а: эксперты в MetaTrader 4' ведут на ошибку 404. Так что нужно поправить ссылки.
Ждем, пока в Альпари поправят ссылки - они обещали.
 
Renat:
Yurixx, что конкретно в документации не так? Приведите, пожалуйста, четкие указания на ошибки и мы это исправим.

Если же Вы хотите иметь максимально детализированную документацию на все случаи жизни, то этого не получится, к сожалению. Вставить аналог MSDN в терминал будет сложно. Чтобы мы не написали, все равно будут вопросы. И даже наличие статей, библиотеки кода, форума и поисковой системы по всему этому хозяйству не всегда поможет.

Тема этой ветки заставила меня ясно сформулировать давно назревшую мысль. Теоретического подхода "дайте мне хорошую документацию/книгу и я переверну мир" недостаточно. Нужна практика с обязательным и самостоятельным наступанием на грабли.

Наша позиция по документации:

  • заниматься интерактивным обучением трейдеров на глобальном уровне во всем мире через специальный сайт MQL4.community
  • предоставить возможность трейдерам помогать друг другу и делиться знаниями
  • дать возможность трейдерам общаться напрямую с разработчиками
  • стимулировать написание статей трейдерами, переводить их на другие языки
  • накапливать информацию в единой точке, чтобы любой мог получить к ней доступ
Я не хочу иметь максимально детализированную документацию на все случаи жизни и т.п. Речь идет просто о нормальной документации. Несколько пожеланий высказанных в этой ветке я объединил в своем посте на 3-й странице. В части документации там было следующее:

Обязательно должны быть главы с описанием (как это написал alex_ant) мехинизма работы MQL-программы. Это то, что может понять каждый трейдер - новичек в программировании еще до начала изучения языка. И описание это должно быть привязано к процессу торговли. Там же можно объяснить чем отличаются друг от друга индикаторы, скрипты и советники, как они ведут себя по отношению к потоку тиков, к торговому серверу, друг другу и т.д.

Больше внимания должно быть уделено структуре MQL-программы, ее основным компонентам - функциям init(), start() и deinit(). В этих функциях состоит существенное отличие MQL от других языков, а места в документации им уделено крайне мало, практически только несколько строк.

Было бы очень здорово просмотреть все статьи словаря и не только устранить ошибки и опечатки, но и привести к общему знаменателю терминологию. Очень часто описание однотипных или вообще одинаковых параметров функций и процедур делается с помощью совершенно разных терминов, и значение этих терминов не поясняется. В результате описание имеется, но смысл и использование некоторых параметров приходится изучать на эксперименте.


Очень важно (совершенно согласен с 4x4ever ) привести в прядок примеры ! Подавляющее большинство примеров в статьях словаря никому ничего не объясняют и ничему не учат. Вообще, пример в одну строку - не пример ! В нормальном справочнике пример позволяет понять и смысл параметров, и порядок использования процедуры/функции, и получаемый при этом результат. И для этого не надо писать свою собственную программу. ИМХО: слабость примеров Словаря MQL - один из главных недостатков документации.

Согласитесь, это не так уж много.

Renat, позиция Вашей фирмы по поводу документации заслуживает всяческого уважения. Однако, обратите внимание, в перечисленных Вами пунктах нет ни одного, который непосредственно касался бы документации. Они все хороши, но это надстройка, а фундамент - это те материалы с помощью которых все изучают MQL и программируют на нем. На сегодняшний день - это Словарь (т.е. собственно документация) и, во вторую очередь, публикации на сайтах. Чтобы работала надстройка, сделайте прочный фундамент. То есть доведите до нужного качества Справочник по MQL.
 

Renat писал (а):
Yurixx, что конкретно в документации не так? Приведите, пожалуйста, четкие указания на ошибки и мы это исправим.


Yurixx:
Renat, позиция Вашей фирмы по поводу документации заслуживает всяческого уважения. Однако, обратите внимание, в перечисленных Вами пунктах нет ни одного, который непосредственно касался бы документации. Они все хороши, но это надстройка, а фундамент - это те материалы с помощью которых все изучают MQL и программируют на нем. На сегодняшний день - это Словарь (т.е. собственно документация) и, во вторую очередь, публикации на сайтах. Чтобы работала надстройка, сделайте прочный фундамент. То есть доведите до нужного качества Справочник по MQL.

Я так понимаю, четкого указания на явные ошибки нет. А жаль.
 
Renat:

Я так понимаю, четкого указания на явные ошибки нет. А жаль.

Обычно в таких случаях, чтобы не напрягать себя, любимого :) поиском конкретных ошибок, даются пачкой многостраничные ссылки на ГОСТы, СНиПы и ISO, с предложением привести продукт в соответствии с указанным списком. Жаль, не помню номера и искать не хочется, а так бы накидал список ;)
Это шутка.

Ренат, а что за новый редактор для сайта Вы тут ранее упоминали, планируя запустить?
 
chv:

Ренат, а что за новый редактор для сайта Вы тут ранее упоминали, планируя запустить?
Мы сделали новую более удобную версию онлайн редактора для форума и раздела статей. Эта версия позволяю гораздо легче создавать сообщения.

Одной из новый возможностей (пока не включена) будет вставка видеороликов. Как своих роликов, так и роликов из YouTube. Скорее всего бету для публичного тестирования запустим в понедельник.
 
Renat:

Renat писал (а):
Yurixx, что конкретно в документации не так? Приведите, пожалуйста, четкие указания на ошибки и мы это исправим.

Я так понимаю, четкого указания на явные ошибки нет. А жаль.


Вы, Renat, слишком торопитесь с выводами. Как видно очень уж хотите отделаться от назойливых "критиков" без лишних усилий. После так красиво провозглашенной позиции фирмы это наводит на мысль, что на самом деле за этими провозглашениями скрывается нежелание прислушиваться к пожеланиям пользователей. Действительно, MQ сама знает что и как ей делать, при чем тут пользователи.

Смею Вас уверить, Вы неправильно понимаете ситуацию. Я вполне могу дать Вам четкие указания на то, что требует доработки. Однако, сначала надо кое-что прояснить. В этой фразе, так убедительно выделенной красным, явно просматривается следующее: укАжете на ошибки - исправим, а сами ковыряться в документации не будем. И формулировка "явные ошибки" тоже наводит на размышления. За 2 года отладки и благодаря помощи участников этого форума количество "явных ошибок" сократилось до минимума и продолжает уменьшаться. Тем не менее, Вы своей фразой даете понять, что указания на другие ошибки, которые не являются "явными", вас не интересуют. А вместе с этим не интересуют и плохие примеры, непонятно написанные объяснения и т.п.

Далее, Вы что же хотите, чтобы я на ВСЕ ошибки документации дал указания ? Нет уж, Renat, извините. Ваша фирма может и не заниматься созданием учебника по MQL, это нормально. Но доработать документацию по языку она должна. Обязана ! Кто еще, кроме создателя языка, должен документировать его ? Как еще, кроме как на основе этой документации, программисты могут научиться использовать этот язык ?

Поэтому, чтобы не быть голословным, привожу характерный пример. Если Вас качество документации не интересует, то Вы, безусловно, найдете почему то, что я написал - ерунда. Если же все-таки есть хоть капля конструктива в этом разговоре, то Вы, без сомнения, поймете о чем это я. Впрочем, Вы и так это прекрасно понимаете.

Тем не менее, пример.

int ArrayRange( object array[], int range_index)
Возвращает число элементов в указанном измерении массива. Поскольку индексы начинаются с нуля, размер измерения на 1 больше, чем самый большой индекс.

Параметры:

array[] - Проверяемый массив
range_index - Индекс измерения.

Пример:
int    dim_size;
double num_array[10,10,10];
dim_size=ArrayRange(num_array, 1);
.

Обычно индексом называют переменную, которая нумерует элементы массива. В данном случае речь идет не об индексе, а о номере индекса. Однако, из фразы "Поскольку индексы начинаются с нуля, размер измерения на 1 больше, чем самый большой индекс. " ни этого, ни чего-то другого понять невозможно. Особенно новичку.

Что значит "Поскольку ..." ? Где это раньше оговаривалось ? Нигде ! Потому, что это специфическая функция и переменная range_index, которая нумерует измерения, не появляется больше нигде. Поэтому надо просто сказать, что нумерация измерений начинается с 0. И номер измерения (а не размер !) на 1 больше, чем самое большое значение переменной range_index (а не "индекс"). А еще лучше не втискивать это все в одно предложение, а объяснить это все последовательно и внятно в 2-3 фразах.

Приведенный в описании пример - это классика Справочника. Что он может прояснить ? Ничего ! Если Вы, Renat, не знаете как должно быть, то посмотрите на картинку в первом посте этой страницы. По крайней мере должна быть распечатка результатов приведенных в примере операций. А какое значение приняла в результате переменная dim_size ? Я знаю, что Вы знаете, но знают ли об этом начинающие изучать язык ?

А даже если бы и было написано, что dim_size=10, кому бы это и что прояснило ? Автор этого примера, наверное из юмористических соображений, во всех трех измерениях массива поставил число 10.

Вот Вам пример отношения к написанию документации. Эпитет к слову "отношение" придумайте сами.
Интересно, сколько "явных" ошибок Вы здесь насчитали ? Думаю, что ни одной.
Однако, заверяю Вас, - таких статей в Справочнике, не содержащих никаких явных ошибок, но существенно понижающих качество содержащейся в нем документации, еще очень много.