Проблема популярности Ruby и Ruby on Rails — плохая документация

Хочу поделиться своими соображениями. Я читал много топиков на тему Ruby, Ruby on Rails, Ruby vs PHP, Python vs PHP. «Каждый кулик свое болото хвалит». Я считаю, что это дело сугубо каждого — какую систему или язык программирования использовать, личные предпочтения, как говорится, на вкус и цвет товарищей еще поискать. Но суть даже не в этом. Я хорошо знаю PHP, не так давно взялся за изучение Ruby и Ruby on Rails. Знаете, как ни странно это звучит, но мне нравятся обе системы — и PHP, и Ruby, возможно даже одинаково. В Ruby есть свои прелести, которые привлекают — мощность самого языка, очень понятный и лаконичный синтаксис (если с толком подойти к изучению), в PHP — простота и все та же лаконичность языка. Хорошие системы, хорошие инструменты, но все же Ruby как-то в роли догоняющего. Что же тут не так?

И вот над чем я задумался. Если Ruby — столь привлекательный и модный ныне язык разработки, то почему же его продвижение идет с неком скрипом? Вроде там все ясно и понятно, но вот чего-то явно не хватает. А не хватает по сути самого главного — хорошей документации. Предвижу много возражений. Да, она есть, но в каком виде? На официальном сайте есть несколько ссылок на доки. Все вроде бы хорошо, всего с избытком. Но! Позвольте-ка, как я могу доверять документации в которой не нашел описания элементарного метода core (!) method_missing, зато в другом источнике — на-то пожалуйста! Плюс ко всему нет каких-то перекресных ссылок на сопутствующие, похожие методы.

И как это все рознится с документацией по PHP. Вот вам сайт, вот вам тут же ВСЯ документация — и описание языка, и функции, и перекрестные ссылки. Я помню, как я начал писать на PHP — я просто открыл сайт и шаг за шагом начал исследовать сначала сам язык, попутно узнавая о функциях. Просто прелесть! За месяц с нуля я написал небольшой сайт вообще без всяких проблем.

Совсем иная картина с Ruby. К изучению Ruby я подошел более основательно — купил книгу, досконально все изучил (кстати, очень рекомендую «Язык программирования Ruby» Д.Флэнаган, Ю.Мацумото), затем приступил к Rails — нашел перевод книги, последовательно по примерам изучал. В принципе там все ясно и понятно изложено. Но вот после окончания прочтения возникает такое чувство, как-будто тебе кратко чего-то объяснили («от опушки леса до чащи лесной довели»), а потом — «дальше давай уж сам как-нибудь, браток, по темному лесу топай, а фонарик и компас, не, мы тебе не дадим — тут же и так все ясно-понятно, мы сами, вон, спокойно по этому лесу бродим и не блуждаем, и ты не заблудишься». А ничего, что я в этом «лесу» впервые?..

Документация по RoR просто отвратительная — там не найти того, о чем не знаешь — нет полного и понятного описания методов, нет описания параметров методов, нет примеров, нет описаний классов и их взаимосвязей. Опять же, парируя возражения, скажу, что те описания, которые есть — это как раз на уровне учебника для начинающих — описано то, что и так в принципе понятно. А куда же дальше идти? Исходники ковырять? Но, позвольте, я не сторонник автоВАЗа, например, именно потому, что эти машины надо почти сразу же после покупки «допиливать». Тут похожая ситуация — изучить авто, чтобы нормально ездить на нем. И к чему это? Я машину покупаю, потому что водителем хочу быть, а не автомехаником. Я хочу пользоваться инструментом, а не познавать его в деталях, да к тому же без инструкции — опять же отсутствие документации. Многие совершенно не представляют, как работает их мобильник, но с успехом им пользуются. Будет интерес — залезу в исходники, но пока вот мне это совершенно ни к чему. Что-то я не припомню, чтобы мне функционал того же PHP на официальном сайте предложили изучать по исходникам. Я хочу использовать язык программирования, фреймворк, при чем хочу на полную мощность, а не только на уровне того, что мне в учебнике преподнесли, развиваться и двигаться дальше, а не топтаться на месте, ковыряясь в исходниках. Поймите правильно, мне не важны детали работы того инструмента, которым я пользуюсь, лишь бы он выполнял все свои функции правильно, и знать обо всех этих функциях хочу, но из документации, «инструкции по использованию инструмента», а не выспрашивать у кого попало и не ползать по инету в поисках.

Насколько я уже убедился на собственном опыте (я в IT-индустрии более 20 лет), выигрывают чаще удобные и доступные системы, и наличие хорошей, удобной документации — это практически половина успеха, а не те системы, где внутри все круто, но стороннему наблюдателю не понятно, да и рассказать некому.

Вот, собственно, мои соображения. PHP, Ruby, Python, C++, Java — лишь один из способов общения с машиной, не более того. И нам всем повезло в том, что мы можем выбирать на чем писать и как писать. Но пока система остается мало доступной для легкого изучения для любого пользователя или программиста, то грош цена всей той крутости, которую она скрывает за отсутствием документации. За примерами ходить далеко не нужно — популярность и широкое использование какого-либо средства разработки — лишь следствие его доступности и наличие удобной и полной документации в частности.

Сразу оговорюсь, что наличие форумов или других разрозненных источников информации я за документацию не считаю. Любая мощная система должна обладать прежде всего полной и удобной документацией. И, я думаю, многие со мной согласятся, что тратить свое драгоценное время на исследование исходников, вместо того чтобы заниматься делом — не самое приятное и полезное занятие. Оно конечно хорошо — знать исходники — типа развивает и все такое, но у меня дел своих полно, а разработчикам Ruby и Ruby on Rails пора бы задуматься над хорошей документацией, иначе так и будут плестись в хвосте столь превосходные средства разработки.
Ads
AdBlock has stolen the banner, but banners are not teeth — they will be back

More

Comments 108

    +5
    Я бы не сказал, что ruby в роли догоняющего, это же не web-язык, у него масса применений в других облостях. Но косяк с документацией есть, тут не поспоришь. Хотя… Документация PHP тоже не фонтан, ее огромная сила в комментариях пользователей под каждой функцией — они больше всего выручают. Вот именно этого ruby и не хватает.
      +1
      Не смотря на то, что Ruby — не только web-язык, это не оправдывает отсутствие нормальной документации.
        0
        Книг — завались. Гугл знает про всё. Какой документации тебе еще надобно, боярин? :)
          +5
          Книги, блоги и т. п. — это не документация.
            +1
            Документация тебе для чего — знания получить, так? Не всё ли равно, откуда знания получать?
              +1
              Далеко не все-равно. Когда все в одном месте, имеет удобную структуру, поиск — оно всегда лучше. Мне вот не хочется в пустую тратить самый драгоценный ресурс — свое время на поиски информации, а потом еще и запоминать, где я что когда-то нашел, чтобы потом при надобности освежить это в памяти.
                0
                А я не трачу свою драгоценную память на запоминание того что «ага, доки по рельсам на этом сайте, доки по руби на том, а по jquery — вот на том».

                Для меня это всё в одном месте. И нужна ссылка обычно на первом месте.
                  0
                  Случаем не эта ссылка?

                  Я вот хочу, посмотрев документацию, сделать то что мне нужно, а не искать готовые варианты, сделанные другими людьми.
                +3
                Нет. Документация должна быть, как минимум, актуальна, а книги и посты в блогах, темы на форумах и т. п. быстро устаревают. Причём основной юзкейз документации — справка, уточнение нюансов и т. п., а не получение знаний вообще. Документацию используют по ходу работы с сабжем, а книги (если это не справочник) читают для поднятия уровня в целом. То есть общий юзкейс — книга (или туториалы и гайды) для получения общего обзора (разной глубины), документация для поиска деталей.
          +1
          Про силу комментариев на php.net — это в точку. Не знаю что бы что я делал, не будь там этих комментов.
            0
            Не только комментарии. Сама документация полная — есть подробное описание функции, всех ее параметров, возвращаемых значений — это основа. Комментарии, это конечно хорошо, но главное — полнота основной информации. Я сам изредка заглядываю в комментарии, но чаще всего мне хватает просто четкого и ясного описания, если есть примеры — еще лучше.
              0
              Я согласен, что дока нормальная, но комменты чрезвычайно при этом полезны.
                0
                Поверьте. И в ПХП полно недокументированного кода. К примеру open ssl расширение. Много ф-ций вообще недокументированы, тут вот ua2.php.net/manual/ru/function.openssl-x509-check-private-key.php параметры — mixed и mixed и пойди разберить — путь ли к файлу ключей это или строковое представление ключа или ресурс какой-то…
                  0
                  В том-то и дело, что в доке по пхп это, скорее, исключение, чем правило
              –1
              > Я бы не сказал, что ruby в роли догоняющего, это же не web-язык, у него масса применений в других облостях.

              Мне кажется большинство проектов на нем все таки для Web.
              +1
              А rdoc, ri и пр., когда можно на локальной машине все посмотреть?

              www.ruby-doc.org/ вполне себе сносная документация.

              Аналогично на каждый gem.
                0
                Я уже привел пример именно с сайтом документации, как раз вот на www.ruby-doc.org я не нашел описания метода method_missing, зато на другом сайте — apidock.com/ — пожалуйста.
                  +1
                  Может я чего-то не понимаю, но вот это что?
                    0
                    А вы попробуйте обычным путем www.ruby-doc.org -> Core -> Methods (поиск). Что-то там я не заметил. Собственно, это тоже проблема, что страницу можно найти только каким-то одним путем, отсутствие ее в результатах поиска на других страницах, нет перекрестных ссылок, о чем я тоже уже сказал.
                      –1
                      Ну извините, если мне что-то надо найти, то я пользуюсь поиском.
                      Скажу больше, я буду пользоваться поиском гугла, если мне надо найти описание будь то пхп, жаваскрипта или руби функции. Это не сравнимо быстрее и информативнее, чем искать на сайтах данных или других языков.
                        +2
                        А не зная о существовании подобных методов вообще что Вы искать начнёте?
                        • UFO just landed and posted this here
                            0
                            Прочтите полностью эту ветку комментариев.
                            +1
                            «ruby catch method not exists» -> вполне таки находит method_missing

                            Правильно составленный запрос даст намного больше информации, чем чтение списка функций.
                              0
                              Оно, конечно, хорошо, когда вы хотя бы знаете о чем спрашивать, а если вас интересует определенная тема, но вы еще даже понятия не имеете, как может называться этот(эти) методы, которые вам могут подойти для решения?
                              Что еще хуже, гугл может найти для вас СТАРЫЕ решения, которые уже в принципе не актуальны для новых версий системы, а может и вообще ничего внятного не найти, если вы занимаетесь разработкой чего-то нетривиального, и до вас никто не исследовал данный вопрос или просто не написал нигде о своем решении.
                          –1
                          В Core наверное нету, потому что это stdlib :)

                          Да документации толком нет, но ссылка которую привел n0ne, вполне все описывает. Да и название метода как-бы намекает на то что это за метод…
                            0
                            Ой, чей-та я вру… Не обращайте внимания…
                              0
                              Да-да-да, там все как бы намекает на что-то… бубен в руки — сразу все проясняется и становится понятным :)))

                              Ничего страшного, со всеми случается ошибиться.
                                0
                                Мне просто кажется что это косяк в генерации доков. Сейчас проверим в исходниках есть ли документация. Можно будет и баг репорт сделать :)
                                  0
                                  Документациявсе-таки есть. Проблема с генерацией судя по всему.
                                    0
                                    Не стоит заморачиваться. Этот метод я только в качестве примера привел. Я думаю, что таких пробелов найдется предостаточно в документации(иях) по RoR и Ruby.

                                    Проблема более масштабная, глобального характера, прямо скажем.
                                      0
                                      ruby-doc.org не содержит документации на private методы. apidock — содержит. Странно конечно, но найти где почитать можно :)
                                        0
                                        Я не спорю, при желании можно найти все что угодно, но вопрос как раз стоит в удобстве использовании системы как таковой, проблема в отсутствии приличной централизованной документации по сложной ситеме. Чтобы не рыться и не искать где попало. Хорошо я знаю об этом методе, а если даже не подозреваю о его существовании, мне тогда что, к ясновидящим направится изволите?
                                          0
                                          централизовано — apidock все таки
                            0
                            Это документация (причем неофициальная) для версии 1.6 (!)
                              +2
                              Но, позвольте, а где же тогда официальная документация? Или разработчики так и будут уповать на интуицию и космический разум новичков (да и профессионалам документация всегда в помощь)?
                          +3
                          А я apidock.com/ юзаю. Есть всё, почти везде есть примеры и можно посмотреть сорс конкретной функции(ещё не разу не пригодилось, если честно). А ещё есть комментарии пользователей, прямо как на php.net.
                          Я много лет писал на php, и перейдя на RoR очень рад.

                          А проблема популярности только в том, что в язык достаточно высокий порог вхождения.

                          Вот отличная иконографика на тему PHP vs Python vs Ruby.
                            –2
                            Вот-вот, порог вхождения. А разработчики Ruby и RoR как-то и не стремяться хоть как-то облегчить жизнь — сделать хотя бы нормальную одкументацию, тем самым хоть как-то понизить этот порог, об чем и речь.
                              +1
                              Не хочу спорить, но меня документация устраивает более чем.
                              Под порогом вхождения, я имел стартовые знания: нужно знать хотя-бы основные паттерны(MVC, Active Record, etc), хорошо представлять себе что такое ООП и знать хотя-бы 1-2 языка программирования(что бы был хороший опыт). То есть Ruby on Rails как первый язык\фреймворк это не самый лучший выбор.
                                0
                                С одной стороны и для PHP+, например, Symfony2 это нужно знать. С другой — ООП в PHP, имхо, сложнее для понимания.
                                  +1
                                  Ну опять же, на пхп можно писать под веб без всех этих знаний и по ходу дела что-то изучать. А на руби писать без фреймворка под веб не вариант.
                                  А на счёт сложнее тяжело сказать, первым я учил пхп и по началу ооп действительно тяжело давался. А теперь я это всё знаю и в руби для меня нет ничего нового в этом плане.
                                    +5
                                    Пхп, имхо, далеко не самый лучший вариант первого языка. Руби точно лучше.
                              0
                              В чём выражается этот высокий порог вхождения?
                              0
                              При наличии Интернет, использование rdoc и ri — это как-то на мазохизм смахивает.
                              Вся проблема разработчиков именно в том, что они надеются на автоматическую генерацию всей доки, что никогда не срабатывает правильно. Я сам грешу тем, что в состоянии написать работающую систему, но мне в облом писать документацию к ней. Подавляющему большинству разработчиков всегда кажется, что все элементарно, все и так понятно, но это далеко не так. Создать нормальную документацию — это тоже большой труд, для чего и существуют отдельные группы разработчиков документации, о чем пора бы уже и разработчикам Руби задуматься — обзавестись такими специально обученными людьми. Где-то слышал, что документацию вообще должен писать посторонний, но знающий систему человек, но не сами разработчики, потому как взгляд со стороны — он более свежий.
                                0
                                Это да, но иногда бывает просто приятней код почитать с комментариями. Как-то пока особых проблем не возникало ни при изучении, ни при непосредственно работе.

                                Сегодня кстати пришлось в код resque залезть, одну штуку посмотреть, так вполне себе хорошо код читается ;)
                              –2
                              Спасибо что подняли этот вопрос. Я в свое время забил на руби и рейлс именно по этой причине. Не мог позволить себе тратить столько времени на изучение самого инструмента разработки
                                0
                                И на чем в итоге остановились?
                                  –1
                                  Дабы не разводить холивар, скажу лишь что инструментов хватает )
                                  0
                                  Да, я кстати тоже по этому поводу откладывал годик
                                  +1
                                  Когда я года три назад начинал осваивать руби и рельсы, тоже удивился такой разбросанной и, казалось, неполной документации. Но тут дело не в ней. Во-первых, руби очень интуитивно-понятный язык, во-вторых — 95% документации, которую читает руби-разработчик — это документация к gem'ам, ведь во многом именно этим прекрасен руби. В-третьих, ситуация с документацией активно меняется.

                                  Да и проблемы развития Ruby/Rails я не вижу на данный момент: сейчас всё как раз набирает обороты, появляются новые молодые специалисты, все больше новых проектов стартуют на рельсах, а профессионалы очень востребованы. Так что, думается мне, в скором времени Руби встанет на то место, куда должен :)
                                    +1
                                    Сдается мне, что была бы отличная документация раньше, спецов уже сейчас было бы гораздо больше.

                                    Об интуитивной понятности — это спорный вопрос. Для новичков все довольно не очевидно. Это я по своему опыту скажу. Да, когда окунаешься в эту среду, там уже проще, но ведь кто-то так и остается на берегу, боясь войти в эту среду, именно потому, что не видит никаких спасательных кругов на своем пути.
                                      +1
                                      Да, соглашусь с вами, пожалуй.
                                      Руби, как правило, привлекает тех людей, которые довольно долгое время уже занимались разработкой. Привлекает, в первую очередь, своим чудным синтаксисом, расширяемостью, и прекрасным Ruby Way. Эту ценность не особо осознают товарищи, которые только начинают свой путь в веб-разработке, да и в разработке вообще.
                                      Именно вся красота руби тогда не дала мне остановиться в его изучении. Ну и еще railstutorial.org, который просто спас меня :)
                                    –2
                                    лучший способ изучить rails — читать сорцы
                                      0
                                      Ну это ты, конечно, слегка загнул :)
                                        –1
                                        отнюдь
                                          0
                                          Ну поздравляю тогда :)
                                      +4
                                      Народ, ну пора уже психологию «вынь да положь», и «мне все должны» менять!

                                      У нас открытое сообщество, увидели, что где-то что-то плохо задокументировано — разобрались, написали доку и отправили ее в репозиторий / написали в блог / и т.п.
                                        –4
                                        А потом Ruby или Rails внезапно снова что-то поменяют и что? Во-первых любой сложный продукт должен быть хорошо задокументирован, во-вторых — разработчики сами должны быть заинтересованы в продвижении своей системы в массы, в третьих — наличие документации именно от самих разработчиков (уж кто как не они должны знать все досконально) как раз и характеризует зрелость самого продукта, в-четвертых — документация должна быть всегда актуальной и удобной в использовании.
                                        Открытое общество, мне кажется, не предусматривает недоделок. Или я ошибаюсь?
                                          0
                                          Да никто никому ничего не должен. Нравится — пользуйся. Не нравится — исправь. Не хочешь — полно и других инструментов, с хорошей документацией :)
                                            0
                                            Да в том то и дело, что все достаточно хорошо документировано, и не понятно, что же еще нужно :)
                                              –1
                                              Хотелось бы очень нечто вроде perldoc.perl.org или www.php.net. Просто ради интереса зайдите и посмотрите внимательно, почитайте, осмотритесь, желательно не предвзято, сравните это все с api.rubyonrails.org и apidock.com
                                              И представьте себя в роли новичка, который в принципе пока и толком-то не знает как и что ему использовать, а не гуру, которому нужно просто вспомнить о методе, который ему уже известен.
                                                0
                                                Ну это нужно скорее сравнивать с guides.rubyonrails.org/
                                                  0
                                                  Вы постоянно сбиваетесь на сравнение языка с фреймворком. У любого фреймворка высокий порог вхождения, т.к. это априори инструмент для ускорения работы профессионалов, а не для новичков. Нравится или нет, но надо понимать внутреннее устройство фреймворка или хотя бы базовые паттерны, чтобы использовать его эффективно. Иначе абстракции так протекут, что захлебнётесь.

                                                  А что касается языков, то изучать их по документации вообще странная затея для новичка. Учебники для кого вообще пишут?
                                                  Я сам когда-то программировал на PHP и могу точно сказать, что у него дела с stdlib обстоят хуже некуда… Вы никогда не сможете объяснить новичку какого хрена strpos пишется без подчеркивания и принимает строку в первом аргументе, а str_replace — с подчеркиванием и принимает строку в третьем аргументе. Т.е. если новичок попытается понять логику построения stdlib в PHP, то у него мозг взорвётся. Не понимаю в каком месте тут низкий порог вхождения…
                                                    0
                                                    Я лишь привожу примеры документации.
                                                    А то, что у фреймворк высокий порог вхождения, так это только лишний раз доказывает, что к нему нужна хорошая документация. Возьмите для примера Yii, Kohana, Zend — там дела гораздо лучше с доками, чем у Ruby on Rails.
                                                    И зачем мне понимать внутреннее устройство работы фреймворк, чтобы работать с ним, скажите мне на милость? Разве фреймворк не для того предназначен, чтобы облегчить работу программиста, а не наоборот нагружать его лишними деталями своего внутреннего устройства?

                                                    Я привел пример сайта www.php.net, потому что там как раз все вместе — и описание языка, и описаний функций библиотеки. Я лично без единой книги выучил php только по одному этому сайту. Дело вкуса — придираться к названиям функций или нет, меня вот это совершенно не напрягает, тем более когда я знаю, что к ЛЮБОЙ функции php есть внятное и полное описание, где в деталях описано, как и что та или иная функция делает, да еще и со ссылками на похожие, сопутствующие функции.

                                                    С доками по Ruby еще более-менее, но вот доки по Rails меня очень разочаровали. Мне нравится Ruby, мне нравятся идеи Rails, но мне не нравится отношение разработчиков, которые оставили столь сложную систему без хорошей документации.
                                                      0
                                                      > Возьмите для примера Yii, Kohana, Zend — там дела гораздо лучше с доками, чем у Ruby on Rails.

                                                      Ну это уже неимоверно толстый троллинг. Видимо дела там гораздо лучше исключительно потому что примеры на PHP :-)
                                                      Других «преимуществ» не видно.

                                                      > И зачем мне понимать внутреннее устройство работы фреймворк, чтобы работать с ним, скажите мне на милость?

                                                      Чтобы не забивать гвозди микроскопом и не строить велосипеды.
                                                      Ваша проблема в том, что Вы не понимаете самого важного: не «работать с ним», а «работать им», «решать задачи его средствами»!!! Фреймворк — это не вещь в себе, это инструмент, а точнее даже ящик с инструментами.

                                                      > Разве фреймворк не для того предназначен, чтобы облегчить работу программиста, а не наоборот нагружать его лишними деталями своего внутреннего устройства?

                                                      Фреймворк безусловно облегчит в разы работу тем, кто понимает как работают абстракции, которые он реализует. А тем, кто ещё и детально знает его устройство, облегчит работу в десятки раз. Всем остальным он только усложнит работу.
                                                      Серебряной пули не существует. Для новичка начинать с использования фреймворка — это тупиковая ветвь эволюции, потому что он не будет понимать почему что-либо работает так, а не иначе.

                                                      > Я лично без единой книги выучил php только по одному этому сайту.

                                                      Ну и что это доказывает? Знание языка самого по себе — это капля в программистских знаниях.

                                                      > Дело вкуса — придираться к названиям функций или нет

                                                      Разве ж это придирки? Это пример косяка в stdlib, коих там сотни… Это весьма критическая проблема — без документации вы в PHP и шагу не ступите, т.к. здравый смысл в stdlib отсутствует напрочь.
                                                        0
                                                        > Других «преимуществ» не видно.
                                                        Если Вы не видите разницу в том, что код с примерами, с ссылками на похожие методы, с полным описанием всех функций (методов), то мне и объяснять дальше не стоит.

                                                        > Чтобы не забивать гвозди микроскопом и не строить велосипеды.

                                                        > Фреймворк безусловно облегчит в разы работу тем, кто понимает как работают
                                                        > абстракции, которые он реализует. А тем, кто ещё и детально знает его устройство,
                                                        > облегчит работу в десятки раз. Всем остальным он только усложнит работу.

                                                        Да, абстракции, но не детали работы всех механизмов внутри. Бред какой-то! Давайте теперь каждый человек будет обязан знать все инструменты наизусть. Я приводил пример с авто, так вот Вы как раз, похоже, из разряда автолюбителей-автомехаников, которые балдеют от автоВАЗа.
                                                        Да, не забивать гвозди микроскопом или не строить велосипеды. Но зато вы предлагаете просто детально изучить эти самые микроскопы и велосипеды. Зачем? Я вот этого не понимаю.
                                                        Я использовал PHP, я работал с фреймворк, и совершенно не интересовался, как и что там внутри. Мне достаточно знать того ЧТО та или иная функция, класс, метод делают, но не КАК они это делают. И, знаете, все прекрасно получалось и получается — без знания внутренностей, со знанием что и как работает только из нормальной, хорошей документации.

                                                        >> Я лично без единой книги выучил php только по одному этому сайту.
                                                        >Ну и что это доказывает? Знание языка самого по себе — это капля в программистских
                                                        >знаниях.

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

                                                        >Разве ж это придирки? Это пример косяка в stdlib, коих там сотни… Это весьма >критическая проблема — без документации вы в PHP и шагу не ступите, т.к. здравый >смысл в stdlib отсутствует напрочь.

                                                        Я думаю, что и вы далеко не уедете в любой сложной системе без документации. Другое дело, что в одних системах документация хорошо оформлена и удобна в использовании, а в других — зарыта в исходниках.

                                                        Пора бы понять, что документация — это благо, это необходимость, она помогает не отвлекаться на детали, а более продуктивно и качественно работать, заниматься своим делом, а не исследовать как и что когда-то кто-то сделал и пытаться вникнуть в детали. По сути любой код для того и пишется, чтобы им потом пользовались в работе, а не для того, чтобы потом другим заново пройти весь тот путь разработки.
                                                          0
                                                          > Если Вы не видите разницу в том, что код с примерами, с ссылками на похожие методы, с полным описанием всех функций (методов), то мне и объяснять дальше не стоит.

                                                          Фишка в том, что у RoR оно не менее полное, чем у к-л другого фреймворка.
                                                          Похожие методы — это вообще ваш личный термин. Что под этим понимается никто не в курсе, приведите хоть 3-4 примера.

                                                          > Я приводил пример с авто, так вот Вы как раз, похоже, из разряда автолюбителей-автомехаников, которые балдеют от автоВАЗа.

                                                          Не согласен. Есть два подхода к инструментам: потребительский и профессиональный.
                                                          В случае с веб-программированием потребительский подход реализуется в рамках CMS, всё остальное предполагает, что вы разбираетесь в устройстве инструментов, а не побежите в автосервис, если у вас бензин закончится.
                                                          Если в рамках ваших метафор, то я призываю программистов быть механиками «Формулы-1», а роль водителя уступить пользователям. А любители автоВАЗа в данном случае — это как раз те, кто изучает фреймворки по документации, т.к., не заглядывая в код, они так навсегда и останутся не более, чем любителями.

                                                          > И, знаете, все прекрасно получалось и получается — без знания внутренностей, со знанием что и как работает только из нормальной, хорошей документации.

                                                          Ну, ну… Сайты-визитки отлично получаются по документации. Когда напишете первое высоконагруженное приложение, тогда и поймёте как сильно заблуждались.

                                                          > Я думаю, что и вы далеко не уедете в любой сложной системе без документации.

                                                          Сложно только то, что непонятно. Если вам понятен исходный код системы, то она уже несложная.

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

                                                          Документация — это лишь описание представлений людей о том как работает код, причём далеко не всегда правильное и актуальное (особо отмечаю, что это касается абсолютно любой документации). Если она описывает код, на языке который вы плохо знаете, то документация — незаменимая вещь. Если же речь идёт о фреймворке на языке, который вы хорошо знаете, то лучшая документация для него — это его код.
                                                            0
                                                            > Фишка в том, что у RoR оно не менее полное, чем у к-л другого фреймворка.
                                                            > Похожие методы — это вообще ваш личный термин. Что под этим понимается
                                                            > никто не в курсе, приведите хоть 3-4 примера.

                                                            Хватит и одного примера, потому как там все описания такого рода.
                                                            Например, практически все описания функций PHP выглядят следующим образом:
                                                            ru2.php.net/manual/ru/function.strpos.php

                                                            слева список строковых функций, снизу примеры и «смотрите также», так вот как раз их я и называю ссылками на похожие функции. По-моему только вы один не поняли о чем я говорю, у остальных вопросов не возникало.

                                                            > Если в рамках ваших метафор, то я призываю программистов быть механиками
                                                            > «Формулы-1», а роль водителя уступить пользователям

                                                            Да-да, вперед! Не думаю, что хоть один механик «Формулы-1» работает без документации, и ему дают просто ковыряться в боллиде, чтобы он смог понять, как же это сложное устройство работает.

                                                            > Ну, ну… Сайты-визитки отлично получаются по документации. Когда напишете
                                                            > первое высоконагруженное приложение, тогда и поймёте как сильно
                                                            > заблуждались.

                                                            Уважаемый, речь идет об инструменте, который вы изучаете быстро и легко благодаря документации, а потом каждый использует в своих проектах инструмент — и не важно, что это — сайт-визитка или портал. И вы очень заблуждаетесь насчет того, что я не писал серьезных проектов. «Когда напишите» — это уже какие-то выводы на пустом месте. Я — профессиональный программист с 20-летним опытом. Неужели Вы полагаете, что все эти 20 лет я ерундой всякой занимался? Осторожнее надо быть с выводами, Уважаемый.

                                                            > Сложно только то, что непонятно. Если вам понятен исходный код системы, то она
                                                            > уже несложная.

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

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

                                                            Полнейший бред! Начиная от " далеко не всегда правильное и актуальное" до «лучшая документация для него — это его код». Вы уж сильно что-то путаете с нормальной документацией. Рекомендую посмотреть непредвзято на сайты популярных фреймворков PHP, документацию к Perl, документацию PHP. Вы увидите, что даже если система и поставляется с открытым исходным кодом, но что-то никто не предлагает изучать ее по исходным кодам. У всех серьезных проектов есть хорошая документация.

                                                            Отвечать Вам более не собираюсь, ибо данный спор уже не имеет смысла. Нравится Вам — используйте исходники — дело сугубо Ваше.

                                                            Скажу лишь, что мне очень хочется видеть проекты Ruby и Ruby on Rails в более зрелом виде, чтобы они были более дружественными для изучения, и как следствие — они станут еще более удобными и еще более популярными.
                                                          0
                                                          Да, еще к слову… Я уже прекрасно понимаю код на Ruby (благодаря прочтенной мною книги), но мне просто жалко тратить свое собственное время на исследование чужих исходников только для того, что мне важно найти просто метод, который делает то-то и то-то, я не стремлюсь понимать детали — код уже разработан, работает без ошибок — этого вполне достаточно, чтобы использовать его, но тем не менее мне снова предлагают заглянуть в исходники, чтобы найти описание, по сути документацию.
                                              +3
                                              Не знаю, у меня проблем с документацией никогда не было. Берется одна хорошая книга, прочитывается. Это стартовый багаж знаний. Затем добавлять немного гугла при необходимости.
                                                –1
                                                Пожалуй, согласен. Информацию о том, как устроены рельсы приходится искать в исходниках, полудюжине книг и на apidock / stackoverflow. Apidock в этом смысле хорош тем, что пользователи там время от времени дописывают новые варианты использования методов.
                                                Вообще, рекомендую почитать Readme-файлы в гемах ActionPack, ActiveModel, ActiveSupport (ActiveRecord, как мне кажется довольно-таки интуитивен, а про ActiveResource я пока ничего сам сказать не могу). Там довольно неплохое описание того, что умеют модули. Это значительно помогает в том, чтобы понять логику рельсов. Впрочем, без чтения исходников всё-равно фиг что поймешь.
                                                  –5
                                                  Согласен. Из «большой тройки» (PHP, Python, Ruby) документация именно Ruby производит худшее впечатление. Аналогично с популярными фреймворками. Сам сейчас начинаю писать на рельсах — большая часть времени уходит на гугление.
                                                    0
                                                    Я на полном серьезе в половине случаев иду в сырцы рельс чтобы понять какие-то определенные нюансы работы некоторых методов, не описанные в документации. Это говорит о том, что документация — говно.
                                                      0
                                                      а можно примеры?
                                                        0
                                                        Метод render класса ActionController::Base умеет столько всего, что в документации даже половины не перечисленно. В частности, нужно было отрендерить паршал с определенным Content-Type.
                                                      +2
                                                      Может я не с тем сравниваю, но после этих двух книг:

                                                      image и image

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

                                                      Более того, после прочтения книги про рельсы, мне было элементарно освоить CakePHP. Такое чувство, что взляли рельсы и заменили язык с Ruby на PHP.
                                                        0
                                                        Я читал те же книги, но «Гибкая разработка...» уже 4-е издание по 3-й версии Rails. И тем не менее, мне не хватает нормальной документации, ну вот хоть убейте, но www.php.net/ в разы лучше, чем api.rubyonrails.org/
                                                          0
                                                          Ну вот когда будет рельсам столько же лет, сколько пыху, тоже, может, будет подобная документация. :)
                                                            0
                                                            У Пыха всегда такие доки были, сколько его помню. Да и, сдается мне, не столь большая разница в возрасте Пыха и Рельсов, чтобы наплевать на доки.
                                                              0
                                                              А кто плюет? Нас всё устраивает. А кого не устраивает, тот может закатать рукава и исправить ситуацию. Опенсорс в действии :)
                                                                –1
                                                                Я уже отвечал на подобный пост, но повторюсь. Разве опенсорс подразумевает недоделки в разработке, в этом его прелесть? А отсутствие документации на сложную систему — это очень значительная недоработка.
                                                                  0
                                                                  Недоделки — субъективны. На взгляд авторов рельсов там вполне может быть всё доделано.
                                                                    0
                                                                    Конечно все доделано… только в том случае, если считать, что разрабатывали они эту систему исключительно для себя и для внутреннего использования, но в том-то и дело, что продукт стал уже достоянием широкого круга общественности. Стоит проявить уважение — снабдить систему приличной документацией. Тут известность и популярность уже предполагает некоторую ответственность.
                                                                      0
                                                                      Ну вот опять позиция «они должны». А они не должны, вот в чем дело.

                                                                      Вот если бы ты платил деньги за рельсы, то тогда другое дело.
                                                                        0
                                                                        А кто-то платит за пхп?
                                                                          0
                                                                          Подумалось только что, это может быть частью специального умысла. Чтобы ограничить приток быдлокодеров в сферу руби и рельсов. Пускай себе в пыхе своем ковыряются.
                                                                            –1
                                                                            Быдлокодеров везде хватает. У меня даже есть живой пример тому. Человек не в состоянии был просто элементарные алгоритмы реализовывать. Дело даже не в стиле написания. Так вот, подумав, что во всем виноват пхп, он пересел на Ruby, потом на Python. Я думаю, что там дела у него обстоят не лучшим образом.
                                                                            «А вы, друзья, как ни садитесь, все ж в музыканты не годитесь.». Среда разработки — лишь инструмент.
                                                                              0
                                                                              Но согласись, что чем ниже порог вхождения, тем быдлокодеров больше. А для веба я не знаю языка с более низким порогом, нежели пых.
                                                                                0
                                                                                Нет, ну давайте тогда изобретем язык просто с огромным порогом вхождения и доки вообще к нему запретим. Эх, какое кристально-чистое сообщество программистов тогда будет на нем писать, сливки общества! :) Что за бред?
                                                                                  0
                                                                                  Так есть такой язык, хаскель называется :)
                                                      • UFO just landed and posted this here
                                                        • UFO just landed and posted this here
                                                          +1
                                                          Вот когда Rails Gudes не было, тогда изучение было хардкором и гугл можно было считать официальной документацией. Сейчас с этим вроде легче.
                                                            +1
                                                            Тут комьюнити немного другое :) Те кто крутится с руби может годами не заходить на офф страничку руби или рельс.
                                                              0
                                                              Тем, кто считает, что документация по php превосходная — советую посмотреть на perldoc.perl.org/ или man perldoc ;-)
                                                                –1
                                                                Да, кстати, очень показательный пример хорошей документации! Сам несколько лет программировал на Perl и проблем с документацией никогда не испытывал. Но это еще более подчеркивает несостоятельность документации RoR и Ruby.
                                                                0
                                                                По поводу method_missing не понял. Зачем вы его искали в API рельсов? Его документацию можно найти в доках по ruby.
                                                                А комменты юзеров реально были бы полезны, вообще странно что никто еще не сделал такой ресурс.
                                                                  –2
                                                                  Я привел это в качестве примера. О том и говорю, что по обеим системам нет нормальной документации, но по рельсам — хуже всего.
                                                                  +3
                                                                  Исходный код Ruby On Rails и есть сама документация. Есть еще кроме официльной документации, альтернативная: railsapi.com/. Прекрасный сайт: railscasts.com. Если Вам не хватает информации блогов и проидексированной информацией google, то, наверное, не стоит продолжать изучение Ruby On Rails. Другой вопрос что на русском языке мало инфы полезной… Если англ. не знаете будет очень сложно, согласен. Документация gem'ов на github вылаживают и wiki тоже в достаточно объемном виде. Не понимаю чего не хватает. Не вижу никаких проблем.
                                                                    0
                                                                    на railsapi, к сожалению, автор забил :( Очень удобный ресурс был, но новшества rails 3.1 — 3.2 он уже не охватывает
                                                                      –1
                                                                      О чем и речь, собственно! Забил, да по сути толком и не начинал — положился полностью на автоматическую генерацию док, как истинный программист. Слепить доку из комментариев в исходниках — это не есть хороший подход к документированию системы.
                                                                        0
                                                                        Так большего ничего и не требуется, руби самодокументируемый язык по сути, поэтому тут и пишут, что исходники читают, он на порядок легче читаются.
                                                                          0
                                                                          может вы не в курсе: api.rubyonrails.org/ — это и есть railsapi, только теперь уже это официальная документация по API Rails.
                                                                            0
                                                                            Вот только вся прелесть railsapi была в том, что там можно было смерджить апи руби и рельс, и искать методы, не заботясь, из какой они библиотеки.
                                                                      0
                                                                      лично я не знаю по памяти ни одного сайта с доками по руби/рельсам и не испытываю по этому поводу никаких проблем
                                                                      нужные мне доки или railstutorial с ответом всегда где-то там на 1-3 позиции
                                                                        +1
                                                                        Я так понимаю эта тема пришла из rubyonrails-talk, но там на неё даже внимания не обратили. Возникает ощущение, что у автора проблемы с чтением и умением гуглить, не нашел method_missing — это просто смешно. Есть отличные книги и по руби, и по рельсам, после прочтения которых все становится намного легче. У каждого языка есть свои особенности, и, обладая достаточными базовыми знания, можно покрывать недостатки документации чтением исходников, так как руби, по сути, очень хорошо читаемый язык. Да, может быть, для человека, работающего с пхп, это не совсем привычно, но мне это даже нравится, узнаешь много нового и полезного, и в дальнейшем это окупается. А если такой подход не нравится, то лучше в руби даже не лезть, но если очень хочется, то уж удосужься потратить хотя бы пол годика на изучения языка, все приходит с опытом.
                                                                        В целом, мне нравится текущая ситуация, и я не очень хочу ещё большей популяризации языка, ни к чему хорошему это не приводит. Рельсы опопсели, растолстели и превратились в ужасного монстра… но это терпимо.
                                                                          0
                                                                          Да, вы правы, я и в другой форум писал, но только для того, чтобы может сами разработчики рельсов увидят. И зря вы считаете, что внимания не обратили, очень даже обратили, но не в группе гугл, а на самом форуме, с которым она сопряжена.
                                                                          С умением читать у меня все в порядке — уже 3 книги прочел по Ruby и RoR.
                                                                          Почему многие умение гуглить путают с нормальной документацией, а?
                                                                          Если вам нравится «как царь-кощей над златом чахнуть» — «знают только избранные, остальным — не дано», то мне вот совершенно не нравится данная ситуация и данный подход разработчиков Ruby и RoR, не нравится такое положение дел, потому и написал эту статью.
                                                                          0
                                                                          Как бы то ни было, но все-таки я освоил эту систему разработки! Хотя все еще недостает хорошей документации.
                                                                          Вот первый проект: www.inet777.ru/portfolios/57/adminka-ruby-on-rails

                                                                          Only users with full accounts can post comments. Log in, please.