Документирование компонентов

[robhrt7]

Привет,

Большое спасибо за интересный проект и активный выход в опенсорс! Меня очень впечатляет ваш серьезный подход к разработке верстки, отсюда собственно и вопрос, как вы документируете UI компоненты в компании?

Возможно вы ранее уже видели/слышали, что я активно занимаюсь идеей создания Style Guide Platform и мы с ребятами разрабатываем движек для этого дела - SourceJS. Вижу что ваш инструмент легко вписывается в наше идеальное видение процесса разработки UI, вот например интерфейс Clarify в SourceJS http://sourcejs.com/specs/example-bootstrap-bundle/carousel/?clarify=true&sections=1.

Clarify берет компонент из общей странницы документации, и позволяет его тестировать в разных шаблонах, упрощая подход Living Style Guide Driven Development. Мы ранее планировали добавить туда плагин для image regression тестирование, было бы интересно совместить ваш инструмент с Clarify, как расширение/плагин.

Если у вас есть подобные решения, я бы с удовольствием хотел бы с вами пообщаться и обменяться опытом.

Если вы еще активно не разрабатываете стайл гайды для своих компонентов, вам так же может пригодиться мой обзор инструментов http://www.smashingmagazine.com/2015/04/13/an-in-depth-overview-of-living-style-guide-tools/.

[Chaptykov]

Привет!

Спасибо за отзыв!

Документирование

Мы не документируем UI-компоненты в полном смысле этого слова. В нашем командном процессе, основную часть функций берет на себя Makeup:

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

Были еще эксперименты по комментариям к отдельным элементам блока, но у нас такой подход не прижился. Тем не менее, такая возможность сохранена на уровне кастомных инструментов.

Makeup — максимально гибкий инструмент, не завязанный на инфраструктуру. У нас в команде мы его используем в качестве Style Guide, с возможностью комфортного ручного регрессионного тестирования и тесной интеграцией с приложением.

Например, у нас есть возможность отрендерить шаблон напрямую, либо использовать весь код модуля приложения, и отрендерить блок методами фреймворка.

Интеграция с Clarify

Было бы очень любопытно. Но у меня есть ощущение, что платформе сейчас нужен другой инструмент для визуальной регрессии. Мы пока не планировали автоматизировать визуальную регрессию. Кажется, что для Clarify нужен аналог Gemini.

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

Мы планируем экспериментировать дальше в этом направлении, но на данный момент такого функционала нет.

Обмен опытом

Мне тоже интересно обменяться опытом, проблемами и решениями.

Предлагаю продолжить в этом треде, и пообщаться лично на FrontendConf.

[robhrt7]

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

Для Clarify мы и думаем использовать Gemini, или подобные инструменты.

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

Мы можем обсудить какую самостоятельную часть из makup я мог бы внедрить в экосистему SourceJS, и что в свою очередь можете позаимствовать вы. Если вы серьезно нацелены на опенсорс, и хотите построить серьезные инструмент, я думаю было бы очень правильным ходом объединить усилия в этом направлении. В сообществе достаточно бурно сейчас развивается тема Стайл Гайдов, и грех не присоединиться к общей волне.

Основная идея SourceJS как Style Guide Platform - построить экосистему инструментов для разработки UI на основе ядра с самыми необходимыми API. Базируясь на плагинах и разных методах настройки, SourceJS можно использовать и как просто стайл гайд, для генерации Bootstrap-like документации, а так же как инструмент для разработки, как ваш Makeup.

Что вы думаете по этому поводу, и есть ли желание вместе построить такую систему?

[robhrt7]

Если получится обсудить на этих выходных, я думаю упомянуть Makeup на грядущем Front-trends.