Привет!

Владислав, ты во многом прав. Мы очень стараемся исправить ситуацию в условиях тех ресурсов, которые у нас есть.

Ниже постараюсь ответить на каждое твое утверждение.

После нескольких попыток подобраться к данной технологии, стало ясно - отсутствие документации никак не продвинет технологию в массы.

Говорить о том, что документация отсутствует все-таки преувеличение. Документации очень много: описаны все инструменты, технологии и каждый блок. Для большинства документов существует 2 версии на русском и английском.

Читать, что-то на форумах, в каких-то статьях и не понятном разделе "Руководства" - очень интересно, но кроме каши не дает ничего.

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

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

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

Думаю, это проблема не БЭМа, а фронтенда в целом. А мы привыкли опережать прогресс ;) Так что, разумеется, мы продолжим развивать код и документация будет устаревать. Помощь с ее актуализацией или хотя бы конкретные баг-репорты нам бы очень помогли.

Нет примеров кратких но самодостаточных, большинство тем возникали на форуме.

Можешь, пожалуйста, сформулировать ТЗ на такие самодостаточные примеры? Что в них должновойти/

Нигде не сказано, что новым трендом в данной технологии является выделения mVc в отдельный bundle design.

Не уверен, что понимаю, о чем речь. Раскрой тему, пожалуйста.

Изобилие bem и enb в разных статьях, в документации должно быть что-то одно.

Почему? Есть make, rake, grunt, gulp, broccoli, brunch, тысячи их. А еще есть bem-tools и ENB. Выбор и конкуренция — двигатель прогресса.

Ситуация вводящая в ступор:

создаем страницу bem create -l desktop.bundles -b index на выходе получаем один файл index.bemjson.js;

Почему это вводит в ступор? Команда звучит буквально так «БЭМ, создай блок index на уровне desktop.bundles». Разве mkdir desktop.bundles/index && touch desktop.bundles/index/index.bemjson.js короче?

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

компилируем bem make, на выходе еще получаем 10 файлов. WTF? Что за файлы, за что отвечают, являются ли они build файлами и не подлежат ручному редактированию? Почему финишные файлы называются по разному, например index.html _index.css _index.js?

Здесь, как мне кажется, есть ответы на эти вопросы, а новый подробный документ про сборку мы пишем прямо сейчас.

Нельзя ли результат компиляции, что не подразумевает ручного редактирование перенести в подпапку distr например?

Можно, конечно. Например, mv desktop.bundles/index/_index.* dist/ Думаю, вопрос был в том, почему этой возможности нет в bem-tools из коробки? Дело в том, что подготовка к продакшену и деплой у каждого проекта свой и не связан с БЭМ-предметной областью. Для этого можно использовать любой из существующих инструментов общего назначения. Тот же grunt или gulp, например.

Очень нужна документация, по каждой технологии, устаревшие технологии документировать не первостепенно.

Вот же они!

Показывать примеры и с подгрузкой данных через API, и динамическое изменение DOM.

Их тоже есть у нас!

Из того, что не критично, но хотелось бы получить:

право переопределять константы BEM_CLASS и BEM_PARAMS_ATTR, ну не нравится мне i-bem и data-bem, хочу получить js и data-js;

Всегда можно положить на уровне переопределения проекта i-bem__internal и переопределить нейминг в JS, а генерацию дата-атрибутов в HTML можно смело переопределить в собственной реализации i-bem.bemhtml.

не нравится именование модулей i-bem__dom, i-bem как-то не вписывается в Code Style.

Я не понимаю, как бы можно было поддержать такую возможность. Имхо, звучит как «не нравится мне jQuery, не вписывается в Code Style». Если это правда принципиально, то всегда можно форкнуть библиотеку.

Из документаций которые покрывают 99% вопросов мне нравится https://docs.djangoproject.com/en/dev/ http://symfony.com/doc/current/index.html http://git-scm.com/doc - это те документации, которые рассказывает и о различных приемах, и о назначении, и полноценные use case.

Мы стремимся к тому, чтобы наша документация тоже покрывала все вопросы, была понятной и актуальной. Если оглянуться назад, видно, что многое уже сделано, но, конечно, еще очень много предстоит сделать в будущем. И тут мы бы не отказались от помощи ;)

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

Будет лучше. Мы обещаем.

Документации очень много, согласен, но в вашем же ответе ссылки ведут на различные источники, т.е. информация то есть, но ее надо искать в разных местах. Видео доклады обычно больше маркетинговые, как кто-то что-то применил, и что получил, а как применял, что использовал, какое API использовалось для достижение определенных целей, там не рассказывают... Баг-репорты буду слать когда в очередной раз начну от начала до конца читать все материалы. Самодостаточные примеры я отдельно пришлю в личном сообщении, когда начну делать продукт, чтоб не выдумывать. В ступор вводят не команды, а появление 10 файлов. Где то в примере по приведенной ссылке присутствует информация про bemhtml.js без разъяснений - это не документация, аналогично про bemhtml. Если файлы генерируются одной командой bem make, то и описание всех этих файлов должно быть в одном месте, например, в виде содержания. Так же нет информации про файлы начинающиеся с "_". Так же не нашел информации про .bh.js, чем bemhtml.js отличается от bemhtml. По использованию bem-tools, если подготовка к продакшену у всех своя (логично), то как минимум надо рассказать, как сделать компиляцию JS и CSS, а HTML не минифицировать, потому что, многие будут ее перетаскивать на свои шаблонизаторы. "Всегда можно положить на уровне переопределения" показать на конкретном примере, не на словах.

Буду надеяться и ждать улучшение документации, а так же ее структуризации.

Спасибо большое за фидбек! Дополню рассказ коллеги и расскажу нашу ситуацию: большинству в сообществе хватает документации и примеров, команда проекта небольшая и посильно старается заполнять пробелы и решать конкретные вопросы. Есть много ребят, разобравшихся с технологией, они помогают отвечать на конкретные вопросы и делятся своим опытом в рамках форума, что видно из постов, мои коллеги отвечают и помогают. На наших офлайн-встречах мы разбираем новости разработки и примеры, есть также видео, включая мастер-классы, статьи, руководства (читай, пошаговые туториалы) и так далее. Если ты просмотрел программу хотя бы 2х наших митапов, то понял, что "видео доклады обычно больше маркетинговые, как кто-то что-то применил, и что получил" нет, все доклады технические. Количество присоединившихся в нам ребят доказывает, что технология в массы двигается, и очень хорошо. Другое дело, что мы к массам не стремимся. Нам бы помочь всем тем, кто вокруг технологии сейчас. А так как порог вхождения за последние пару лет снизился драматически, это число растет, и мы делаем все, что можем и мотивируем нам помогать. Как я уже говорила, команда у нас небольшая. Добавлю — посты вида мягко говоря «у вас все плохо и ничего непонятно», к сожалению, никак не помогают и не мотивируют команду. Посты вида «расскажите, пожалуйста, как работает? Будет ли в ближайшем будущем? Хочется, чтобы?» помогают. Проект в опенсорсе, читай, у всех есть возможность не только требовать, но и помогать. Спасибо!

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

Фактически сейчас есть 3 основные места: сайт bem.info, наша организация на github со всем кодом и видео на tech.yandex.ru, которое, конечно, нужно тоже представить на bem.info (это есть в планах).

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

Тут не соглашусь. У нас достаточно много чисто технических мастер-классов, где с нуля собирается работающий сервис. Чисто маркетинговых докладов скорее меньшинство.

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

Спасибо, будем ждать!

В ступор вводят не команды, а появление 10 файлов. Где то в примере по приведенной ссылке присутствует информация про bemhtml.js без разъяснений - это не документация, аналогично про bemhtml. Если файлы генерируются одной командой bem make, то и описание всех этих файлов должно быть в одном месте, например, в виде содержания. Так же нет информации про файлы начинающиеся с "_". Так же не нашел информации про .bh.js, чем bemhtml.js отличается от bemhtml.

Дело в том, что bem make — это команда запуска сборки. А то, что она соберет зависит от конфигурации. Результат может быть совершенно разным. Приведу такую аналогию: ожидать, что в документации к bem make будут описаны все возможные результаты сборки — это как ожидать, что в readme к grunt окажутся все возможные резултаты применения плагинов.

Поэтому документацию по bemhtml следует искать в разделе Технологии. Там все подробно описано.

Что касается файлов с подчеркиваниями, то они подробно описаны здесь.

Хотя, как я и писал выше, сборка описана не достаточно прозрачно и мы работаем над новым документом.

По использованию bem-tools, если подготовка к продакшену у всех своя (логично), то как минимум надо рассказать, как сделать компиляцию JS и CSS, а HTML не минифицировать, потому что, многие будут ее перетаскивать на свои шаблонизаторы.

Если под компиляцией подразумевается обфускация и оптимизация, то все это есть из коробки, если запустить сборку с переменной окружения YENV=production (см. ссылку выше).

А HTML мы не минимизируем, мы изнально генерируем его в одну строку. Если есть необходимость получить отформатированный HTML, достаточно применить любой бьютифаер, например tidy.

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

Если в качестве примера смотреть на структуру project-stub, то потребуется положить необходимые переопределения в https://github.com/bem/project-stub/tree/bem-core/common.blocks/

Скажем, чтобы изменить data-bem на data-js, потребуется создать папку i-bem с файлом i-bem.bemhtml и таким содержанием: https://github.com/bem/bem-core/blob/v2/common.blocks/i-bem/i-bem.bemhtml#L322-L473 и на строке https://github.com/bem/bem-core/blob/v2/common.blocks/i-bem/i-bem.bemhtml#L427 заменить data-bem на data-js.

Буду надеяться и ждать улучшение документации, а так же ее структуризации.

Улучшения неприменно будут. Что-то обнволяется буквально каждый день, зачастую даже на выходных.