Rundown

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

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

  • Поддержка многоязычного кода
  • Легкая навигация по CMS для внутренних пользователей
  • Полная поддержка white-label
  • Живите в домене Stream по адресу https://getstream.io/docs/
  • Ревизионный контроль
  • Автосохранение при изменении
  • Подставка для стола
  • Маркированные и нумерованные списки
  • Поддержка совместной работы в реальном времени

В первую очередь мы искали гибрид CMS / Google Docs для редактирования нашей документации.

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

Открытие

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

К сожалению, ни один из перечисленных выше продуктов CMS не отвечает всем требованиям. Ближайшим, кто оказался победителем, был Contentful; однако после недели создания прототипа Contentful мы поняли, что в нем нет тех функций, которые мы искали в CMS. Не было поддержки таблиц и нескольких языков, не было редактирования в реальном времени для нескольких пользователей, и, что более важно, у нас не было полного контроля над моделью данных, поскольку Contentful использует схему стиля MongoDB.

В поисках шифера

Сланец оказался победителем в наших выводах. Это полностью настраиваемая структура для создания редакторов форматированного текста с десятками плагинов для поддержки того, что нам нужно с точки зрения CMS. Лучше всего то, что Slate построен на React, что позволяет нашей интерфейсной команде быстро строить поверх фреймворка.

По умолчанию Slate предоставляет все необходимое с точки зрения разработки для создания полностью функциональной и надежной CMS с нуля (конечно, поверх Slate). Если вы еще не проданы, посмотрите живую демонстрацию Slate здесь.

Строительство из шифера

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

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

Под капотом Slate относительно прост и по существу предоставляет оболочку для API HTML5 contentEditable, но с дополнительными ограничениями, которые помогают сохранять плавность и предсказуемость для понимания. Это означает, что вы должны создать все дополнительные функции, помимо набора текста в редакторе, и обратные вызовы, такие как onPaste и т. Д. Однако экосистема плагинов Slate на npm растет с каждым днем, и сказать, что их легко использовать, читать и создавать - ничего не сказать.

Вот некоторые из пользовательских блоков, которые мы создали для CMS, чтобы удовлетворить наши потребности:

  • Вкладки кода (Предварительные блоки с вкладками с выбором языка и подсветкой синтаксиса из PrismJS)
  • «Переменные среды», которые автоматически преобразуются в значения (например, ключ API пользователя) во внешнем интерфейсе.
  • Список параметров для отображения аргументов и их типов для вызовов API каналов и чата.
  • Настраиваемая таблица с произвольным количеством строк и столбцов
  • Блоки, зависящие от языка, которые могут содержать любое количество вложенных блоков внутри и которые условно отображаются в зависимости от языка, выбранного пользователем при просмотре документации.
  • Необработанный блок HTML для добавления HTML непосредственно на текущую страницу документации, чтобы разрешить использование настраиваемых элементов, для которых у нас еще нет выделенных блоков или которые не имеют смысла в качестве блока.

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

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

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

Плагин прослушивает cmd + v, проверяет контент, который будет вставлен, и, если он находит допустимый HTML для наших примеров кода, он автоматически создает блок CodeTab с отдельная вкладка для каждого языка с подсветкой синтаксиса и отступами.

В целом, с точки зрения разработчика, работать со Slate - одно удовольствие.

Сопряжение с Django REST Framework

Нет ничего более производительного, чем Django Rest Framework для раскрутки простого CRUD API. Вот почему мы решили использовать его для развертывания нашего API для поддержки серверной части Docs CMS.

Мы создали модели для раздела, страницы и обратной связи. Затем мы включили реверсию на странице. Reversion - это прекрасная небольшая библиотека, которая предохраняет вас от потери изменений.

На разработку всего API ушло всего несколько часов. Большую часть этого времени ушло на написание тестов, чтобы убедиться, что все работает. Сегодня, в Stream, мы делаем большую часть нашей разработки на Go. Однако для простых вещей, таких как API CRUD, Python - прелесть: его легко реализовать и понять всем в команде.

Представляем Stream Docs CMS

Благодаря взаимодействию Slate и Django REST Framework, Stream с нуля создал полностью функциональную (и красивую) CMS. Без Slate все это было бы невозможно - спасибо разработчикам.

Вверху у нас есть несколько элементов управления, которые позволяют нам настраивать содержимое страницы. А с правой стороны у нас есть раздел комментариев, похожий на Google, где люди в команде могут оставлять @mentions - они автоматически отправляются по электронной почте соответствующему пользователю, когда в строке обнаруживается электронное письмо.

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

Последние мысли

По мере того, как мы продолжаем создавать дополнительные функции в Stream Docs CMS, мы продолжим писать о наших выводах. Опять же, мы не можем достаточно отблагодарить команду и участников на Slate за фантастический фреймворк, который они создали. Без него у нас не было бы собственной CMS.

Если вы хотите создать собственную CMS, мы рекомендуем вам пропустить фреймворки, представленные в нашем разделе «Обнаружение», и сразу перейти к Slate. Вы удивитесь, насколько легко это реализовать.

Если вы хотите ознакомиться с документацией Stream, посетите https://getstream.io/docs!

До скорого. Удачного документирования! ✌️