Edit me

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

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

Обзор подхода docs-as-code описан в разделе Инструменты Docs-as-code.

В этом разделе рассказ Автора курса Тома Джонсона о проблемах, с которыми он и его команда технических писателей столкнулись при внедрении подхода docs-as-code в большой компании. (Рассказ от первого лица)

Предыдущие процессы

Ранее наша команда публиковала контент через систему управления контентом Hippo (от Bloomreach). Hippo похож на WordPress или Drupal, но основан на Java, а не на PHP (что делало его привлекательным для Java-ориентированного предприятия, которое ограничивал PHP, но все еще нуждалось в CMS-решении для публикации).

Чтобы опубликовать страницу документации, технические писатели должны были создать новую страницу в Hippo CMS, а затем вставить HTML-код для этой страницы (или попытаться использовать редактор WYSIWYG в Hippo CMS). Если у вас есть 50 страниц документации для публикации, вам нужно будет вставить HTML-код на каждую страницу CMS по одной. Первоначально многие писатели использовали такие инструменты, как Pandoc, для преобразования своего контента в HTML, а затем вставляли его в Hippo CMS. Такой подход ctrl+С ctrl+V утомительным, склонным к ошибкам и примитивным.

Когда я взялся за дело, я отстаивал использование Jekyll для генерации и управления HTML, и я начал хранить проекты Jekyll во внутренних репозиториях Git. Я также создал макет в Jekyll, который был специально разработан для публикации в Hippo. Макет включал специфичную для документации боковую панель (ранее отсутствовавшую в Hippo на детальном уровне) для навигации по всему контенту в определенном наборе документации. Этот макет Jekyll включал несколько стилей и скриптов для переопределения настроек в CMS.

Несмотря на это нововведение, наш процесс публикации все еще включал вставку сгенерированного HTML (после сборки Jekyll) страница за страницей в CMS. Таким образом, мы только частично использовали docs-as-code и нам еще предстояло пройти долгий путь. Одним из принципов использования docs-as-code является создание выходных данных непосредственно с сервера (так называемое «непрерывное развертывание»). Другими словами, вы включаете логику публикации на сервере, а не запускаете процесс публикации с локального компьютера

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

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

Преимущества интеграции в большую систему

Почему мы хотели перейти к docs-as-code? В большинстве крупных компаний существует множество надежных, разработанных внутри компании инструментов, которыми могут воспользоваться технические писатели. Подход docs-as-code позволит нам интегрироваться в надежную корпоративную инфраструктуру, которую разработчики уже создали.

Инструменты документирования часто являются независимыми, автономными инструментами, которые предлагают полную функциональность (такую ​​как контроль версий, поиск и развертывание) в пределах их собственной системы. Но эти системы часто являются черным ящиком, то есть вы не можете открыть их и интегрировать в другой процесс или систему. Благодаря подходу docs-as-code у нас была возможность адаптировать наш процесс для полной интеграции в инфраструктуру компании и процесс развертывания веб-сайта. Часть этой инфраструктуры, которую мы хотели подключить, включала следующее:

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

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

Конечные решения

В конце концов, вот решение, которое мы реализовали. Мы сохранили наш проект Jekyll во внутреннем Git-репозитории - тех же Git-репозиториев, которые другие инженеры использовали почти для каждого программного проекта, и которая была подключена к системе управления сборкой. После того, как мы поместили содержимое документа Jekyll в основную ветвь репозитория Git, конвейер сборки начал собирать проект Jekyll непосредственно с сервера (аналогично GitHub Pages).

Процесс сборки от репозитория Git до развернутого веб-сайта занял около 10 минут, но техническим писателям ничего не нужно было делать в течение этого времени. После того, как вы набрали несколько команд в своем терминале (слияние с веткой gamma или production, а затем отправка обновления в источник), процесс развертывания начался и запустился сам по себе.

В первый день запуска нашей новой системы команда должна была опубликовать 40 новых страниц документации. Если бы мы все еще работали в Hippo, публикация заняла бы несколько часов. Еще более болезненным было то, что срок их выпуска был ранним утром, часом до рассвета, поэтому команде пришлось бы публиковать 40 страниц в Hippo CMS примерно с 4 до 6 часов утра, неистово копировать и вставлять HTML, чтобы успеть к выпуску и надеясь, что ничего не напортачили.

Вместо этого, с новым процессом писатель просто слил свою development ветку c веткой production и отправил обновление в репозиторий. Десять минут спустя все 40 страниц были в прямом эфире на сайте. Она была сбита с толку! Мы знали, что это начало новой главы в процессах команды. Нам всем казалось, что с наших плеч снято значительное издательское бремя

Проблемы с которыми столкнулись

Я подвел итоги успеха и общего подхода, но было много вопросов и препятствий при разработке процесса. Я подробно опишу эти основные проблемы в следующих разделах.

Неспособность сделать это самостоятельно

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

Во время ожидания мы доработали нашу тему и процесс Jekyll, нарастили навыки Git и перенесли весь контент из старой CMS в kramdown Markdown. Несмотря на это, поскольку сроки реализации проекта все больше задерживались и отталкивались, мы не были уверены, что полоса пропускания группы инженеров когда-либо уменьшится. Я хотел прыгнуть с корабля и просто развернуть все сам с помощью плагина S3_website на AWS S3.

Но когда я исследовал доменные политики, требования к серверу и другие корпоративные стандарты и рабочие процессы, я понял, что самодельный подход не сработает (если я не обладаю гораздо большими инженерными знаниями, чем в настоящее время). Учитывая наш корпоративный домен, политики безопасности требовали, чтобы мы размещали контент на внутреннем сервере уровня 1, который должен соответствовать требованиям безопасности и другим стандартам. Стало ясно, что это потребовало бы гораздо больше технических и серверных знаний и времени, чем у меня, а также времени на обслуживание, если бы я управлял сервером после выпуска. Поэтому нам пришлось ждать.

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

Понимание друг друга

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

И наоборот, мы плохо понимали мир инженера. Мне казалось, что все, что им нужно было сделать, это загрузить HTML-файлы на веб-сервер, что казалось простой задачей. Я чувствовал, что они слишком усложняют процесс ненужными рабочими процессами и макетами. И какова была проблема с хранением контента в S3 и выполнением динамического поиска, основанного на сопоставлении постоянных ссылок? Но у них уже был процесс публикации контента на существующем сайте, поэтому они более или менее следовали тому же процессу сборки.

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

Выяснение размера репозитория

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

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

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

Изначально наша команда начала хранить контент в отдельных репозиториях. Когда у меня были обновления для темы Jekyll, я думал, что могу просто объяснить, какие файлы нужно изменить, и каждый технический специалист будет обновлять файлы своей темы. Это оказалось не сработало - технические писатели не хотели делать обновления для файлов темы. Проекты Jekyll устарели, и затем, когда у кого-то возникла проблема, я понятия не имел, на какой версии темы они были.

Затем я выступил за объединение всего контента в одном репо. Мы перенесли все эти отдельные автономные репо в одно главное репо. Это хорошо работало для обновления темы. Но вскоре длительное время сборки (1-2 минуты для каждой сборки) стало болезненным. Мы также столкнулись с предупреждениями о размере в нашем репо (изображения и другие двоичные файлы, такие как документы Word были включены в репо). Иногда возникали конфликты слияния

Долгое время сборки было настолько неприятным, что мы решили вернуться к отдельным репозиториям. Нет ничего хуже, чем ждать 2 минуты, пока ваш проект будет собран, и я не хотел, чтобы другие технические писатели ненавидели Jekyll, как Hippo. Молниеносное время автогенерации с Jekyll является частью его магии.

Креативные решения для распространения тем по репозиториям

Я придумал несколько креативных способов, позволяющих передавать файлы темы в несколько небольших репозиториев полуавтоматическим способом. Моим первым решением было распространение темы через RubyGems, которая является официальным решением Jekyll для создания тем. Я создал gem темы, открыл ее исходный код(см. Проект Jekyll Doc) и отработал рабочий процесс, чтобы выпускать обновления gem темы и вставлять их в каждый репозиторий.

Работало все хорошо (так, как задумано). Однако оказывается, что наша система управления сборкой (инженерная система, используемая для создания выходных данных или других артефактов из репозиториев кода) не смогла собрать Jekyll с сервера с помощью Bundler, что требуется от RubyGems. (Bundler - это инструмент, который автоматически получает нужные gems для вашего проекта Jekyll на основе используемой версии Jekyll. Без Bundler каждый писатель устанавливает локальный gem jekyll и создает проект Jekyll на основе этой версии gem.)

Мое понимание системы управления сборкой было ограниченным, поэтому мне пришлось полагаться на инженеров для их оценки. В конечном итоге нам пришлось отказаться от использования Bundler и просто собрать с использованием jekyll serve, поскольку инженеры не могли заставить Bundler работать с системой сборки. Поэтому у меня все еще была проблема распространения одной и той же темы в нескольких репозиториях.

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

Затем я нашел способ распространения темы через Git subtrees. Git subtrees работали в нашей системе сборки (хотя команды были странными), и это сохраняло короткие сроки сборки. Однако, когда команда инженеров начала подсчитывать все отдельные конвейеры сборки, которые им нужно было создать и поддерживать для каждого из этих отдельных репозиториев (около 30), они сказали, что это не очень хорошая идея с точки зрения обслуживания.

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

Было много контента и настроек репо, но в конце концов, архитектура, состоящая из двух больших репо, была правильным решением. На самом деле, в ретроспективе, я бы не возражал, если бы у меня был один репо для всего.

У каждого репо был свой проект Jekyll. Если у меня было обновление каких-либо файлов темы (например, макетов или включений), я копировал обновление вручную в оба репозитория. Копировать файлы было проще, чем пытаться разработать автоматизированный метод. Это также позволило мне тестировать обновления в одном репо, а затем разворачивать их в другом репо. Чтобы сократить медленное время сборки, я создавал специфичные для проекта файлы конфигурации, которые каскадировались с файлом конфигурации по умолчанию и создавали только один каталог. Этот специфический для проекта метод конфигурации позволил сократить время сборки до обычного молниеносного времени менее 5 секунд.

Позвольте мне представить здесь немного больше подробностей о том, как мы сократили время сборки, потому что именно по этой причине многие выбирают Hugo вместо Jekyll. Чтобы сократить время сборки, мы создали файл конфигурации для конкретного проекта (например, acme-config.yml), который по умолчанию устанавливает все каталоги в publish: false, но перечисляет один конкретный каталог (тот, с содержимым, который вы работает над) как publish: true. Затем, чтобы собрать Jekyll, вы каскадно настраиваете файлы конфигурации следующим образом:

jekyll serve --config _config.yml,acme-config.yml

Файлы конфигурации справа перезаписывают файлы конфигурации слева. Это работает довольно хорошо.

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

Обеспечение того, чтобы все работали с одной и той же версией Jekyll

Еще одна проблема заключалась в том, чтобы каждый собрал проект, используя одну и ту же версию Jekyll. Обычно вы включаете Gemfile в ваш проект Jekyll, который указывает версию Jekyll, которую вы используете, и затем каждый, кто создает проект с этим Gemfile, запускает Bundler, чтобы убедиться, что проект выполняется с этой версией Jekyll. Однако, поскольку у нашего конвейера сборки были проблемы с запуском Bundler, мы не могли гарантировать, что все использовали одну и ту же версию Jekyll.

В идеале вы хотите, чтобы все в команде использовали одну и ту же версию Jekyll для создания своих проектов, и вы хотите, чтобы эта версия соответствовала версии Jekyll, используемой на сервере. В противном случае Jekyll может выдавать ошибки. Позже не будет желания обнаружить, что некоторые списки отображаются неправильно или что некоторые примеры кода неправильно выделяются из-за несовпадения gems. Без Bundler все версии Jekyll, будут отличаться. Кроме того, последней поддерживаемой версией Jekyll в системе управления сборкой была более старая версия Jekyll (в то время это была версия 3.4.3, которая зависела от более ранней версии Liquid, которая значительно медленнее создавала сайт Jekyll).

В конце концов инженеры обновились до Jekyll 3.5.2, что позволило нам использовать Liquid 4.0. Это обновление версии сократило время сборки с 5 минут до 1,5 минут. Тем не менее, Jekyll 3.5.2 зависел от старой версии rouge gem, что давало нам проблемы с подсветкой синтаксиса кода для JSON. Процесс обновления gem в системе управления сборкой был для меня чужой территорией, а также был в новинку для инженеров.

Чтобы все были синхронизированы, мы попросили каждого писателя проверить свою версию Jekyll и вручную обновить ее до последней версии. Этот запрос (который некоторые игнорировали), оказалось, не был большой проблемой, так как не было большой разницы между версиями Jekyll (по крайней мере, тех функций, которые мы использовали).

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

Выяснение процессов перевода

Выяснить правильный процесс перевода также было сложно. Мы начали переводить источник Markdown. Наш поставщик переводов подтвердил, что их процесс приема может обрабатывать Markdown как исходный формат, и мы провели тесты, чтобы подтвердить это. Однако после нескольких проектов по переводу оказалось, что они не могут обрабатывать контент, смешивающий Markdown с HTML, например документ Markdown с таблицей HTML (и мы почти всегда использовали таблицы HTML в Markdown). Поставщики будут считать каждый элемент HTML как сущность Markdown, что приведет к увеличению оценки затрат.

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

Однако, если мы отправляли поставщикам только HTML-вывод Jekyll, это затрудняло применение обновлений. В Jekyll (как и большинством генераторов статичных сайтов) ваша боковая панель и макет упаковываются в каждую страницу документа. Если вам нужно добавить новую страницу на боковую панель или обновить какой-либо аспект макета, работая с выводом HTML (а не с источником Markdown), вам нужно будет отредактировать каждый отдельный экземпляр HTML-файла, чтобы сделать эти обновления по всей документации. Такого мы не ждали и не хотели.

В итоге процесс, который мы разработали для обработки содержимого перевода, включал ручную вставку переведенного HTML-кода в страницы проекта Jekyll, а затем включение этих страниц в вывод, как и другие страницы Markdown. Позже мы развили процесс создания файлов-контейнеров, которые предоставили необходимые метаданные frontmatter, но которые использовали включения для извлечения содержимого тела из возвращенного HTML-файла, предоставленного поставщиками перевода. Получилось немного ручного труда, но приемлемо, учитывая, что мы не так часто переводили контент.

URL для переведенного контента также должен иметь другой baseurl. Вместо вывода содержимого в папке / docs/ необходимо вывести переведенный контент в / ja/docs/ (для японского языка) или /de/docs/ (для немецкого языка). Однако у одного проекта Jekyll может быть только одно значение baseurl, как определено в файле _config.yml по умолчанию. baseurl у меня была автоматизирован во многих местах темы.

Чтобы учесть новый baseurl, мне пришлось включить несколько хаков, чтобы добавить языковые префиксы к этому пути и настроить параметры постоянной ссылки в каждой переведенной боковой панели, чтобы встроить файл в правильный каталог ja или de в выводе. Это сбивало с толку, и если что-то сломается в будущем, мне потребуется время, чтобы разгадать логику, которую я реализовал.

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

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

Другие проблемы

Было несколько других проблем, о которых стоило бы упомянуть (но не заслуживающих полной разработки, как в предыдущих разделах). Я кратко перечислю их здесь, чтобы вы знали, с чем можно столкнуться, применяя подход docs-as-code.

Перемещение контента из устаревшей CMS

У нас, было около 1500 страниц документации на 10 наших писателей. Перенос всего этого контента из старой CMS был сложной задачей. Кроме того, мы решили оставить некоторые устаревшие материалы в CMS, так как их не стоило переносить. Создание сценариев перенаправления, которые бы правильно перенаправляли весь контент на новые URL-адреса (особенно с измененными именами файлов), не отвлекаясь от устаревших страниц CMS, было сложной задачей. Инженеры хотели обрабатывать эти перенаправления на уровне сервера, но им нужен был список старых и новых URL.

Чтобы программно создать записи перенаправления для всех страниц, я создал сценарий, который повторяется на каждой боковой панели документа и генерирует список старых и новых URL-адресов в формате JSON, который команда разработчиков могла бы включить в свой инструмент перенаправления. Это работало довольно хорошо, но миграция URL-адресов с помощью комплексных перенаправлений требовала большего анализа и работы.

Внедрение новых процессов при поддержке старых

Пока наш новый процесс находился в стадии разработки (и еще не был запущен), нам пришлось продолжать поддерживать возможность писателей создавать выходные данные для старой системы (вставка содержимого страница за страницей в устаревшую Hippo CMS). Любое внесенное нами изменение должно было также включать старую логику и макеты для поддержки старой системы. Приспособление нескольких шаблонов и сценариев было особенно трудно с содержанием перевода, так как это требовало такого другого рабочего процесса. Возможность переноса нашего контента в новую систему при продолжении публикации в старой системе без внесения обновлений в обоих местах была свидетельством гибкости Jekyll. Мы создали отдельные макеты и файлы конфигурации в Jekyll, чтобы удовлетворить эти потребности.

Один из самых больших взломов был со ссылками. Hippo CMS требовала, чтобы ссылки были абсолютными ссылками, если вставлять HTML-код непосредственно в представление кода, а не с помощью редактора WYSIWYG (как бы безумно это ни звучало, это правда). Мы создали скрипт в нашем проекте Jekyll для заполнения ссылок либо абсолютными, либо относительными URL-адресами в зависимости от целей публикации. Это был нестандартный способ создания ссылок (по сути, мы рассматривали их как переменные, значения которых мы определили с помощью свойств в файле конфигурации). Это сработало. Опять же, гибкость Jekyll позволила нам разработать необходимое решение.

Постоянные изменения процессов документирования

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

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

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

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

Такой опыт заставил меня осознать, что большинство технических писателей не любят возиться с инструментами или экспериментировать с новыми авторскими подходами. Они научились писать и публиковать контент и обижаются, когда вы изменяете этот процесс. Это создает чрезвычайное количество стресса в их жизни. И все же мне нравится пробовать новые подходы и методы. Как без экспериментов узнать существует ли лучший способ что-либо сделать?

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

Стилизация документации внутри большого сайта

Еще одна проблема была со стилями документации. У команды инженеров не было ресурсов для обработки нашей технической документации, поэтому я в итоге создал таблицу стилей (длиной 3000 строк) со всем пространством имен CSS, отнесенным к классу docs (например, .docs p, .docs ul и т.д.). Я реализовал пространство имен, чтобы стили не влияли на другие компоненты сайта. Многое из этого CSS я просто скопировал из Bootstrap. Инженеры включили эту таблицу стилей в свои другие стили для веб-сайта.

Однако в JavaScript мы столкнулись с коллизиями пространства имен и должны были обернуть наши функции jQuery в уникальное имя, чтобы избежать конфликтов (конфликты в конечном итоге нарушат инициализацию некоторых сценариев jQuery). Эти конфликты пространства имен со сценариями не были заметны локально и были видны только после развертывания на сервере, поэтому тестовая среда постоянно переключалась между разрывом или не разрывом боковой панели (в которой использовался jQuery). В результате видение сломанных компонентов создало чувство паники среди инженеров и страх среди технических авторов.

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

Переход на рабочий процесс Git

Хотя может показаться, что Jekyll был инструментом для изучения, более сложной задачей стало знакомство с основанными на Git рабочими процессами для документирования. Git требовал некоторого изучения и знакомства с рабочими процессами командной строки и контроля версий.

Некоторые писатели уже имели опыт работы с Git, в то время как другие должны были изучить его. Несмотря на то, что мы все изучили команды Git, я не был уверен, что все использовали одни и те же процессы для извлечения, добавления и объединения контента (есть много способов как выполнить похожие задачи).

Было много случаев, когда кто-то случайно сливал ветку development в master или обнаруживал, что две ветки не будут объединяться, или ему приходилось удалять контент из мастера и возвращать его в разработку и т.д. Выяснение правильного процесса в Git это не тривиальное начинание. Даже сейчас я иногда нахожу ошибку форматирования, потому что маркеры конфликта Git >>>>>>> и <<<<<<< находят свой путь в контент, возможно, из-за ошибочного слияния. У нас нет никаких скриптов проверки (пока), которые бы смотрели на такие маркеры-заглушки, так что немного обескураживало внезапное столкновение с ними.

Достижение баланса между простотой и надежностью в инструментах документации

В целом, мы должны были поддерживать почти невыполнимое требование при взаимодействии менее технических участников (таких как менеджеры проектов или администраторы вне нашей команды), а также продвинутых писателей. Требовалось, чтобы процессы документооборота были достаточно простыми для техников, не являющихся техническими специалистами, для обновления (аналогично тому, как они это делали в старой CMS), и в то же время обеспечивали достаточную надежность инструментария документации для удовлетворения потребностей технических писателей, которым часто требуется контент из одного источника, переменные реализации, повторное использование фрагментов, вывод в PDF и многое другое.

В конце концов, учитывая, что наша основная аудитория и участники были разработчиками, мы предпочли инструменты и рабочие процессы, с которыми разработчики знакомы. Чтобы внести существенный вклад в документацию, мы решили, что нам, в некоторой степени, нужно понимать Git, Markdown и Jekyll. Для не технических пользователей мы направили их в графический интерфейс (аналогичному графическому интерфейсу GitHub), с которым они могли взаимодействовать для внесения изменений в хранилище. Тогда мы бы смерджились и развернули их изменения.

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

Создание масштабируемой системы

Хотя мы использовали инструменты с открытым исходным кодом, наше решение масштабировалось для предприятия. Поскольку контент использовал Markdown в качестве формата, любой мог быстро его освоить. А поскольку мы использовали стандартные процессы и инструменты Git, инженеры могли легче подключиться к системе.

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

Для масштабирования создания текстов не требовалось никаких лицензий или мест. Автор использовал редактор Atom (или другую IDE) открывал проект и работал с текстом, рассматривая документы как код.

В течение первых нескольких недель после запуска нашей системы мы обнаружили, что инженерам нравилось вносить обновления, используя те же инструменты проверки кода, которые они использовали в программных проектах. Такое использование инструментов обзора кода упростило рабочий процесс редактирования. Но это также создало больше знаний с нашей стороны, потому что это означало, что нам нужно будет изучить эти инструменты проверки кода, как перейти к системе проверки кода, как объединить обновления из обзоров и так далее. Попытка оценить вклад документа, глядя на файл diff в инструменте обзора кода, скорее раздражает, чем помогает. Я предпочитаю видеть контент в полном контексте, но инженеры обычно просто хотят сосредоточиться на том, что изменилось.

Кроме того, предоставление полномочий другим группам потребовало от нас создания подробных инструкций, что само по себе было целым проектом документации. В нашем руководстве было создано более 30 тем, которые объясняли все: от настройки нового проекта до публикации из командной строки с помощью Git, создания PDF-файлов, навигационных таблиц, вставки всплывающих подсказок и многого другого. Учитывая, что эта документация использовалась только для внутреннего использования и не использовалась для внешних целей, руководители предприятий не видели в ней особой ценности и не хотели, чтобы мы выделяли для нее большую пропускную способность. Тем не менее, это заняло много времени. Сделать хорошую документацию сложно, и, учитывая вопросы и возникающие проблемы, я понял, насколько контент должен быть упрощен и отлажен. (Если авторы не могли следить за этим, они звали меня на помощь, тратя еще больше моего времени.)

К сожалению, когда мы начали проект, мы не обеспечили его ресурсами и финансированием для его текущего обслуживания и поддержки. Во многих отношениях работа над проектом была похожа на работу над проектом с открытым исходным кодом. Хотя для документирования нашего набора инструментов и рабочих процессов еще предстоит проделать большую работу, наши официальные приоритеты всегда были сосредоточены на внешнем обращении с контентом документации. Почти никто не хотел тратить время и энергию, необходимые для поддержки внутреннего процесса создания документации. Хотя большая часть этой проблемы могла быть устранена с помощью сторонних решений для хостинга и развертывания (таких как CloudCannon), компания предпочла создавать свои собственные инструменты, но не полностью выделять ресурсы для их обслуживания и документирования.

Заключение

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

Я изложил здесь проблемы, чтобы подчеркнуть тот факт, что реализация docs-as-code - это немалое начинание. Это не обязательно должно быть занятие, которое занимает месяцы, но в большой компании, при интеграции с инженерной инфраструктурой и выстраиваете процесс, который будет масштабироваться и расти, это может потребовать приличного количества инженерных знаний и усилий.

Если вы внедряете docs-as-code в небольшой компании, вы можете упростить процессы и использовать систему, соответствующую вашим потребностям. Например, вы можете использовать GitHub Pages или плагин S3_website для публикации на AWS S3 или, что еще лучше, использовать платформу непрерывного развертывания, такую ​​как CloudCannon или Netlify. (Об этих инструмента написано подробно в разделе Хостинг и варианты развертывания.) Я мог бы выбрать один из этих подходов, если бы разрешили, и если бы у нас не было команды технической поддержки для реализации описанного мною рабочего процесса.

Кроме того, внедрение инструментов для меня несколько смешано. Глубокое знание инструментов документирования имеет решающее значение, когда вы внедряете свое решение. После того, как вы закончили, вам больше не нужна эта глубина знаний, и осознание удручает. Эфемерная потребность в инструментальных знаниях, вероятно, объясняется тем, что так много консультантов специализируются на инструментах - они едут в город, настраивают вещи, а затем везут свои вагоны в следующий город, чтобы повторить шоу. Но если вы работаете на полную ставку, и ваша основная работа - разработка контента, а не инструментов, то как вы находите время и поддержку для развития необходимых знаний об инструментах: когда вы внедряете систему, или после того, как все реализовано и работает без сбоев?

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

И все же платформы и инструменты редко бывают статичными в течение любого промежутка времени. Даже Jekyll постоянно выпускает новые версии, реагируя на изменения в интернете и тенденции технологических потребностей. Так что, возможно, через несколько лет мы снова пройдем весь этот процесс. Несмотря на это, у меня есть желание и возможности работать с инструментами для документации, и я люблю пачкать руки в коде.

Слайды и ссылки на переизданный контент

Слайды презентаций, которые охватывают темы, перечисленные в этой статье:

Другие посты о Docs Like Code в блоге автора:

Чтобы узнать больше о документах как о коде в целом, см. Книгу Anne Gentle Docs Like Code.

🔙

Go next ➡