В Ripple мы используем собственный инструмент под названием Dactyl для компиляции и создания нашего технического контента в рамках нашего подхода «документы как код». Dactyl - это генератор статических сайтов, аналогичный Jekyll, Hugo и другим. Мы не собирались создавать еще один инструмент в многолюдной области, но он органично развивался с нашими потребностями, и мы обнаружили несколько преимуществ, связанных с разработкой самого инструмента. В Ripple мы верим в преимущества открытого исходного кода, поэтому мы делаем Dactyl доступным для разработчиков под разрешающей лицензией MIT с открытым исходным кодом на нашем GitHub.
Основы
Говорят, что контент на первом месте, а в случае с Дактилем это буквально правда. Мы начали с технической документации, написанной на Markdown, и нам нужен был способ ее проанализировать и опубликовать на веб-сайте. Markdown великолепен: он похож на простой текст, поэтому с ним легко начать. Существует множество инструментов, которые могут его редактировать, и он широко используется в различных организациях.
Для документации по программному обеспечению, которая находится между технически мыслящими разработчиками программного обеспечения и техническими писателями, ориентированными на язык, Markdown - это надежный формат моста, который оба типа команд удобны для редактирования. Сотрудничество между людьми разных ролей является ключом к отличной документации программного обеспечения.
Одно только содержание не делает для полной документации, все же. Пользователям также нужны структура, навигация, форматирование и визуальные стили. Эти вещи составляют пользовательский опыт для документации, и большая часть хорошего пользовательского опыта в документации - предсказуемость: все должно работать согласованно, одинаково, в разных документах.
Выполнение этого с веб-сайтом создает существенную занятую работу. Когда одна страница увеличивается до двух, вы должны обновить старую страницу, чтобы сделать ссылку на новую. Когда пять страниц увеличиваются до шести, все пять старых страниц необходимо обновить, чтобы добавить новую страницу. Эта утомительная работа мешает доставлять новую документацию, которая волнует людей.
Вот почему в самом начале Dactyl был всего лишь скромным 100-строчным сценарием для автоматизации такого рода процессов: анализа содержимого документации и помещения его в шаблоны, которые нужно было обновлять только один раз.
Сегодня это все еще ядро Dactyl. Он переносит нас от простого текстового Markdown к красиво отформатированным веб-сайтам, таким как xrpl.org с автоматическими оглавлениями, согласованными верхними и нижними колонтитулами и многим другим. Это только начало для генератора статических сайтов. Dactyl развивается вместе с документацией Ripple и XRP Ledger с момента его создания 5 лет назад.
Особенности, особенности, особенности
За прошедшие годы мы добавили надежные функции для решения новых задач по мере их возникновения. Ниже приведен обзор некоторых интересных решений, которые Dactyl предлагает сегодня:
- Проверка ссылок. Неработающие ссылки и 404 ошибки - ужасный опыт, но найти их все становится довольно сложно, когда у вас есть сотни страниц документации с гиперссылками. Средство проверки ссылок, встроенное в Dactyl, находит и сообщает о неработающих ссылках, поэтому мы можем отловить их перед публикацией или быстро ответить, если старая ссылка умирает.
- Единый источник, поэтому документы, руководства и примеры кода можно повторно использовать для сопутствующих продуктов и руководств. Подобно тому, как программное обеспечение работает: один раз напишите код и импортируйте его там, где это необходимо, единый источник позволяет нам писать полезные фрагменты текста один раз и использовать их снова и снова. Когда эти фрагменты нуждаются в обновлениях, одно изменение автоматически распространяется на все, что от них зависит. Для контента, который не работает одинаково во всех контекстах, препроцессор Dactyl с одним источником также поддерживает синтаксис для условного форматирования и другого процедурно генерируемого контента.
- Экспорт в PDF. Некоторым клиентам Ripple необходим доступ к документации из чувствительных областей финансовых учреждений, где доступ в интернет тщательно контролируется. Возможность распечатать бумажную копию для переноса в эти области является важной особенностью корпоративного решения Ripple, RippleNet. Принц выполняет большую часть тяжелой работы по экспорту PDF, но это особый случай с одним источником: Dactyl использует специализированные шаблоны для более элегантных, удобных в использовании PDF-файлов, которые не похожи на те, кто только что напечатал веб-страницу.
- Плагин архитектуры для постобработки. Это позволяет нам предлагать функции, выходящие за рамки изначально поддерживаемой Markdown, такие как примеры кода с вкладками, значки состояния и специально стилизованные блоки выноски.
- Мультиформатный экспорт. В дополнение к HTML и PDF, Dactyl может экспортировать в более «стандартную» GitHub-разметку Markdown (после применения правил единого источника), а также в формат JSON, специально разработанный для загрузки в ElasticSearch, для обеспечения поиска нашей корпоративной документации.
- Проверка стиля. Английский язык сложен в освоении, но техническое письмо не должно быть художественным и цветочным. Техническое письмо должно быть простым для понимания. Dactyl поставляется со списком рекомендаций по умолчанию, вдохновленным PlainLanguage.gov для замены слов и фраз более простыми альтернативами. Это не может поймать все, но это хорошая отправная точка для поощрения краткого письма на простом английском языке.
- Живые изменения. Запустите Dactyl в фоновом режиме, и он автоматически перестроит ваш локальный экземпляр сайта при каждом внесении изменений.
Вывод
В Ripple мы видим нашу миссию - заставить деньги перемещаться так же легко, как информацию - не спринт и не марафон, а одиссея: многолетнее путешествие с поворотами, подъемами и спадами. Имея это в виду, имя Дактиля вдохновлено метром древнего героического стиха.
Так же, как дактил - это всего лишь один шаг в эпической поэме, так и Дактил - всего лишь один шаг в создании эпической документации. Как команда, мы продвинулись довольно далеко в этом путешествии, но многое еще предстоит сделать. Мы надеемся, что вы присоединитесь к нам, чтобы сделать будущее лучше, шаг за шагом.
Уникальность
