Сравнение трех наиболее часто используемых современных инструментов документирования пользовательского интерфейса в экосистеме Vue.
Почему мы это делаем
Внутренняя документация часто является проблемой для инженерных групп, мы все знаем, что отличная документация - это вложение, но в то же время ее очень дорого писать, невероятно сложно поддерживать и она противоречит скорости разработки, необходимой для быстрого - подвижная, подвижная компания. В этой быстро меняющейся среде некоторые могут даже возразить, что к тому времени, когда вы напишете и исправите документацию, вам придется все реорганизовать, таким образом аннулируя саму документацию.
В прошлом мы достигли точки, когда документация во фронтенд-проектах практически отсутствовала. Люди приходят и уходят, и со временем части кодовой базы стали унаследованными, потому что никто не знал, как они себя ведут и, что еще хуже, как они должны себя вести.
Это может привести к разочарованию, к большому количеству времени, потраченному на исправление некоторых ошибок, которые были бы тривиальными с документацией, а также к более длительному времени адаптации для новичков.
Устаревший код: код, который никто не хочет поддерживать
Мы достигли точки (большей) стабильности, и необходимость облегчения адаптации новых разработчиков и создания надежного и всеобъемлющего набора тестов подталкивает нас к улучшению нашей текущей документации для разработки компонентов внешнего интерфейса (в основном js).
Наши требования
Нам нужна документация для разных библиотек, часто с разным объемом. Одна библиотека может отвечать за HTTP-запросы, другая - помощник js, третья - библиотека компонентов… и так далее.
У нас нет строгих требований, мы просто хотим, чтобы наша документация была красивой и эффективной (необходимая информация должна быть легко доступна, поэтому поиск будет отличным) и не будет слишком сложным в обслуживании, автоматические инструменты будут отличными.
Один плюс для документации библиотеки компонентов - это возможность создавать интерактивные примеры (быстро проверить результат на странице документации), чтобы пользователь сразу почувствовал и начал использовать компоненты.
Что мы уже сделали
Как мы уже говорили, теперь у нас есть несколько «общих библиотек», и особенно для этих общих, потребность в хороших документах огромна.
Для этой цели мы разделили библиотеки на две группы, одну для библиотек, в которых есть Пользовательский интерфейс и один для остальных: библиотека, выполняющая HTTP-запросы, находится в последней группе.
Мы думаем, что согласованность между документами - это здорово, но эффективность и ремонтопригодность лучше, поэтому мы не заставляем себя выбирать только один инструмент. .
Сначала мы изучили инструменты для библиотек, не относящихся к пользовательскому интерфейсу. Для этого существует множество инструментов, но мы сразу выбираем один, потому что у нас уже был опыт работы с ним, и он отлично работал.
Documentation.js
Это отличный инструмент, потому что он автоматически анализирует jsdoc и создает из него файлы разметки или HTML. Результат по умолчанию не самый лучший, но он выполняет свою работу.
Для библиотек, которые предоставляют компоненты пользовательского интерфейса, мы оценили некоторые инструменты на основе нашего технического стека. Поскольку мы используем Vue, мы сосредоточились на этих трех библиотеках, которые соревнуются за звание лучшей: Storybook, Vue Styleguidist и VuePress.
Вот итоги нашего решения:
ИСТОРИЯ
Как говорится на его веб-сайте:
Storybook - это инструмент с открытым исходным кодом для разработки компонентов пользовательского интерфейса изолированно для React, Vue и Angular. Это делает создание потрясающих пользовательских интерфейсов организованным и эффективным.
Сообщество привлекает к нему все больше и больше внимания, и оно этого заслуживает. Это отличный инструмент, способный решить (возможно) все варианты использования.
ЗА
- интерактивный: по умолчанию он позволяет пользователю «играть» с компонентами. Это огромный плюс, потому что не только пользователь / разработчик может читать API компонентов, но и позволяет им также видеть компонент, изменять свойства и сразу же ощутить эффект.
- супер обширный: он предлагает огромное количество подключаемых модулей, и некоторые из них великолепны, например storyshot для запуска наборов тестов для компонентов внутри самой документации.
МИНУСЫ:
- по умолчанию не самый красивый: нужно немного поработать, чтобы сделать его «красивым» (темы есть, но есть над чем поработать).
- требует много времени: требуется больше времени по сравнению с двумя другими инструментами, чтобы подготовить и запустить первую полную документацию.
VUESTYLEGUIDIST
Это еще один инструмент, специально предназначенный для создания документации по компонентам. На этот раз для компонентов Vue (он был создан как форк от react styleguidist, поэтому, если вы являетесь пользователем React, он у вас может быть).
Он генерирует документацию на основе комментариев ( расширение языка jsdoc) в объявлениях исходного кода и файлах уценки.
ЗА:
- автоматически: автоматически создаются документы путем анализа комментария, похожего на jsdoc. По этой причине это инструмент, который стоит выбрать, если вы хотите получить хорошую документацию за минимальное время, потому что вам просто понадобится хорошая документация внутри определений компонентов.
- Экосистема Vue: не одна из самых известных официальных библиотек Vue, но это одна из них, поэтому, вероятно, со временем ожидается хорошая поддержка.
МИНУСЫ:
- гибкость: многие вещи выполняются автоматически, это хорошо, но также и плохо, кажется, что сделать что-то нестандартное очень сложно, и мы опасаемся, что со временем это может стать для нас проблемой.
- немного глючит: с его помощью мы обнаружили несколько ошибок, поддержка была отличной, но все же не идеальной.
- limited: нам было сложно документировать директивы (официального способа сделать это не удалось) и миксины, поэтому вы все равно пишете разные части самостоятельно.
ВЮПРЕСС
Генератор статических сайтов на базе Vue
Это не инструмент для документации, это просто генератор статических сайтов.
Он создан Эваном Ю (создателем Vue.js), и его главная цель - быть простым и производительным, создавая веб-сайт с учетом файлов разметки и Vue.
ЗА:
- официальный: это инструмент, который используется большинством библиотек с открытым исходным кодом для написания своей документации. Излишне говорить, что он работает хорошо и предлагает огромную поддержку сообщества.
- красиво: по умолчанию выглядит красиво. Кроме того, легко выполнить незначительную настройку.
- универсальный: он анализирует файлы MD, но внутри них вы также можете писать HTML и Vue, поэтому, если вы установите свою библиотеку в качестве плагина в экземпляре Vuepress 'Vue, вы можете использовать свои компоненты в документах ( другие инструменты также имеют аналогичные возможности).
МИНУСЫ:
- не автоматически: вы должны писать документацию в файлах MD, здесь нет синтаксического анализа jsdoc или подобных вещей. Хорошо, что вы можете использовать также HTML и Vue внутри этой уценки;
- Отрисовка на стороне сервера: для установки и использования вашей библиотеки в документации (например, для создания интерактивных примеров) она должна быть дружественной к SSR, потому что Vuepress компилирует все в статический сайт, то есть в среду node.js.
Выбор
Мы считаем, что Storybook - наиболее полный инструмент, но он также требует наибольшего количества времени, чтобы довести документацию до состояния готовности к производству.
VueStyleguidist - очень хороший инструмент, отлично подходит для большинства вариантов использования, но, вероятно, для некоторых предприятий он все еще не идеален.
В конце концов мы решили, что Vuepress - лучший выбор для наших нужд, он является промежуточным звеном между двумя другими инструментами. Это просто статический сайт, за которым не стоит никакого автоматического волшебства, но его простота позволяет легко настроить его в будущем.
Классные детали
Вы помните, как мы говорили, что не ограничиваем себя одним инструментом, потому что нам нужен лучший для разных случаев? Мы также сказали, что было бы здорово иметь единый внешний вид для всей документации, это обеспечило бы более единообразный пользовательский интерфейс.
Мы выбрали Documentation.js для библиотек, не относящихся к пользовательскому интерфейсу, и Vuepress для библиотек пользовательского интерфейса. Само собой разумеется, что эти два инструмента не дают одинаковых результатов для конечных пользователей.
Посмотрим, что мы можем с этим поделать.
Мы можем попытаться стилизовать оба вывода одинаково. Например, создать тему для Vuepress и тему для documentation.js или просто создать тему documentation.js, аналогичную теме по умолчанию для Vuepress (потому что последняя уже довольно хороша).
Documentation.js не ограничивается экспортом результата только в формате HTML, это также дает вам возможность получить вывод в формате уценки. Vuepress принимает уценку в качестве входных данных для создания статического сайта ... Вы видите, куда я иду?
Эти два инструмента идеально подходят. Мы создали скрипт узла, который запускает documentmenation.js, создавая уценку, а затем строит статический сайт Vuepress, начиная с этого источника. Таким образом, у нас есть единый стиль для библиотек, независимо от того, какие инструменты мы используем.
Для библиотек пользовательского интерфейса документация по-прежнему ручная, но мы также думаем, что этот тип документации «менее скучно» создавать, и интерактивные примеры по-прежнему будут создаваться для каждого конкретного случая, поэтому мы думаем, что приемлемый компромисс.
Не такие уж крутые детали
Для библиотеки компонентов пользовательского интерфейса мы хотели создать интерактивные примеры, чтобы улучшить взаимодействие с пользователем. Мы не смогли просто установить нашу библиотеку в качестве плагина Vue в экземпляре Vuepress ’Vue, потому что наша библиотека не поддерживает SSR (рендеринг на стороне сервера). Это заставило нас потерять немного времени на поиски того, что мы можем с этим поделать.
Лучшим вариантом было бы модифицировать библиотеку, чтобы она была готова к SSR, но это потребует слишком больших усилий, мы можем запланировать это в будущем.
Вместо этого мы сделали следующее:
Мы создаем небольшую HTML-страницу для каждого примера, который хотим показать, помещаем его в папку .vuepress / public, чтобы они автоматически обслуживались вместе с документацией. Затем в разметке Vuepress мы создаем iframe (вы можете писать там HTML), который указывает на правильный пример.
Возможно, это не самое элегантное решение, но оно работает достаточно хорошо, а также отделяет примеры от самой документации, поэтому вы не получите сочетание двух (конечно, если библиотека была установлена как плагин, вы можете добиться такой же чистоты, разделив примеры с помощью специальных компонентов).
Чтобы упростить жизнь разработчикам и упростить ведение документации для новичков, мы создали шаблон HTML для этих примеров, который автоматически устанавливает все необходимое, нам просто нужно заполнить 3 заполнителя: один для стиля, один для шаблона и один для скрипта.
На мой взгляд, самым большим недостатком этого подхода является то, что фреймы работают медленно и когда вы загружаете документации вы видите, как пример появляется после всего остального контента. Возможно, это не самая большая проблема, но для конечного пользователя это все равно неприятно.
Мы не могли легко изменить способ загрузки и отрисовки страницы, по этой причине мы использовали восприятие конечного пользователя: мы добавили в примеры анимацию постепенного появления (логика исчезновения встроена в только что упомянутый шаблон, поэтому делать нечего, он генерируется автоматически для каждого примера, гарантируя, что он будет и в будущих)
Все это решение iframe работает достаточно хорошо.
Это код для примера шаблона:
И это скрипт, который мы импортируем, который обрабатывает установку плагина и анимацию затухания:
ИСХОД
Мы очень довольны результатами, использование одной и той же технологии для всех библиотек дает единообразный стиль, улучшающий взаимодействие с конечным пользователем.
Мы используем это решение для управления всей нашей интерфейсной документацией и очень довольны эффективностью , автоматизация и качество продукции, которого мы смогли достичь. Все наши новые библиотеки теперь следуют этому стандарту.
Что Вы думаете об этом? Вы бы выбрали другой подход? Мы рады услышать ваше мнение, не стесняйтесь обращаться к нам или писать в разделе комментариев ниже.
