Привет! Меня зовут Глеб Свистунов, в YADRO я руковожу разработкой производственной документации — то есть документации, сопровождающей производство. Мы разрабатываем документацию для технологических процессов: руководства по сборке, прошивке, тестированию и другие документы по технически сложным устройствам, у которых могут быть сотни или даже тысячи разных конфигураций.
Представьте себе конструктор LEGO «Сокол тысячелетия» на 7500 деталей. Они приходят в одной коробке расфасованными по десятку-другому пакетиков. Только с помощью точной, однозначной, полностью соответствующей набору инструкции можно собрать из этой горы деталей модель космического корабля.
Сборщики серверов на конвейере тоже получают для сборки лоток с деталями. Но в отличие от «сокола», который мы будем неспешно собирать долгими зимними вечерами, здесь у сборщика есть строго 20 минут на один сервера, после чего уже нужно приступать к следующему. Поэтому нужна еще более четкая инструкция, на понимание и воспроизведение которой требуется минимум усилий и времени.
Чтобы быстро и экономически эффективно создавать инструкции такого уровня для устройств с множеством конфигураций, наша команда технических писателей разработала новый подход к документации. О нем и пойдет речь в статье.
Для начала проиллюстрирую сложность устройств на более понятном примере. По каким параметрам можно выбрать смартфон? Их множество: марка, модель, цвет, встроенная и оперативная память, процессор и т. д. Если наложить все эти параметры друг на друга, мы получаем множество комбинаций. Каждый новый параметр будет кратно увеличивать вариативность в зависимости от того, сколько значений для него возможно.
В enterprise-оборудовании подобная сложность может достигать колоссальных масштабов. Вариативных параметров здесь еще больше. У серверов, например, это количество и модель процессора, модулей оперативной памяти, накопителей, наличие карт расширения, портов ввода-вывода и многое другое. Хотя из-за взаимного влияния параметров некоторые комбинации параметров могут отсутствовать, эти дополнительные условия усложняют логику документа — что увеличивает итоговый размер документа.
Один документ на все сценарии сразу — или отдельные на каждый?
Представим, что у нас есть технически сложный продукт с высокой вариативностью параметров. Чтобы написать инструкцию по его сборке, мы можем придерживаться одного из двух стандартных подходов.
Одна инструкция на все сценарии (конфигурации) сразу. Один документ — значит, нет дублирования информации. Но эта экономия для технического писателя отчасти нивелируется за счет описания более сложной логики многоуровневых сценариев и учета параметров со взаимным влиянием. Для продукта, скажем, с 1500 конфигураций создание такой инструкции занимает в среднем 150 часов.
Отдельная инструкция на каждый сценарий. Здесь каждая отдельная конфигурация продукта определена однозначно, техническому писателю не нужно учитывать сложную логику и взаимное влияние параметров. Недостаток же — в количестве документов. Для того же продукта с 1500 конфигураций нужно создать 1500 инструкций, каждая займет примерно 25 часов, в итоге получаем 37 500 часов. Очевидно, что писать отдельные инструкции экономически нецелесообразно.
Теперь посмотрим на эти подходы со стороны пользователя — сборщика сервера. Вот инструкция по одному из этапов сборки — установке модулей оперативной памяти:
Представим, что нам нужно установить восемь модулей для двух процессоров. В таблице приведена информация из расчета на один процессор — получается четыре модуля. Сборщику нужно найти строчку с нужным количеством, запомнить разъемы (А0, C0, G0, E0), найти их у каждого процессора. И это только один из многочисленных этапов сборки по инструкции. А время на один сервер у сборщика ограничено в среднем 40 минутами — и ему надо пройти все этапы, дополнительно анализируя информацию на каждом.
Теперь посмотрим на отдельную инструкцию для восьми модулей RAM при двух процессорах:
Здесь нет избыточной, дублирующейся или требующей анализа информации. По своей доступности эта инструкция сравнима с инструкцией к LEGO: только четкие и последовательные шаги точно для имеющейся конфигурации. С такой инструкцией сборщик установит оперативную память быстрее и вероятность его ошибки ниже.
Эффективность производства — наш приоритет, но что делать с уймой часов для подготовки отдельных инструкций? Представляем третий подход.
Концепция динамической документации
Динамическая документация в нашем контексте — это документация, которая формируется четко в соответствии с текущей задачей пользователя, сама подстраивается под его конкретный кейс, текущую конфигурацию продукта.
Реализация такого подхода требует изменений в работе с исходниками. В ходе подготовки их разделяют на три группы:
вариативные параметры, которые изменяются в разных конфигурациях продукта,
постоянные части инструкций, что должны присутствовать вне зависимости от конфигурации продукта,
переменные части инструкций, включение которых зависит от вариативных параметров.
Рассмотрим эти группы на простом примере — инструкции по сборке кухонного гарнитура:
Инструкция включает четыре части. Далее на иллюстрациях я буду выделять оранжевыми скобками постоянные, синими — переменные части инструкции и вариативные параметры.
Во введении перечислены компоненты, которые кухонный гарнитур может включать или не включать. Все введение можно обозначить как переменную часть инструкции.
Пункты 1.1–1.4 описывают подготовку рабочего места. Эти шаги не зависят от конфигурации гарнитура, в ракурсе нашей методологии это постоянная часть инструкции. В пункте 1.5 предложения начинаются с «если», что указывает на вариативные параметры. Соответственно, пункт 1.5 — это переменная часть.
В секции про монтаж шкафов есть вариативные параметры — разные типы шкафов — на которые указывают слова «зависит от высоты», «может быть», «либо». К ним прилагаются переменные части инструкции.
В последней части есть два вариативных параметра — линейная или угловая столешница. На переменную часть документа указывают слова «иногда» и «в случае».
Мы выделили в инструкции постоянную и переменную части:
Представим теперь, что нужно собрать конкретную конфигурацию: линейный кухонный гарнитур со стеновой панелью, разноуровневыми навесными шкафами, без короба под вытяжку.
Адаптируем общую инструкцию: убираем все, что касается короба под вытяжку, одноуровневых шкафов и углового формфактора кухни. В порядке установки оставляем только вариант со стеновой панелью. Вот что осталось:
Этот вариант не содержит ничего лишнего, и работать по нему проще. От единой исходной инструкции со всеми возможными конфигурациями мы перешли к динамической инструкции, которая включает только то, что необходимо для сборки именно нашего кухонного гарнитура.
Подход динамической документации в YADRO
Создание динамической документации начинается с мегаспецификации — описания всех возможных элементов изделия. В соответствии с мегаспецификацией мы готовим множество частей инструкций и по ней проверяем, что это множество достаточно для описания любой конфигурации продукта.
Приступая к работе с продуктом — например, сервером, — сборщик сканирует прилагаемый к нему штрихкод. В нем зашифрована конкретная конфигурация сервера. Конструктор получает ее как входящий запрос и фильтрует из множества атомарных частей инструкции только те, что актуальны для запрошенной конфигурации. Затем генерирует документ с ними и возвращает его сборщику.
Для наглядности приведу содержание общей инструкции по сборке одного из наших серверов. В ней 435 страниц, это целая пачка бумаги:
А вот результат работы конструктора динамической документации. Сгенерированный по конкретной конфигурации документ уменьшился до 135 страниц:
По итогам работы конструктора инструкция сократилась более чем в три раза, и в ней сборщик может идти по порядку, от первого шага до последнего, ни на что не отвлекаясь.
Внедрение подхода в YADRO
Изначально система автоматической генерации документов требует значительных затрат. Если конфигураций оборудования всего несколько, то раздельные инструкции проще и быстрее написать вручную, чем создавать под них систему.
В нашем случае разработка самой системы динамической документации и подготовка контента для первых четырех продуктов в ней заняли в сумме около 1300 человеко-часов. Этот самый тяжелый и затратный этап включал изменение логики, наполнение и отладку системы и согласование изменений с технологами.
На данный момент мы собрали из исходников документы для 647 конфигураций серверов. Даже при таком сравнительно небольшом количестве инструкций мы простым делением получаем затраты на один документ в размере 2 человеко-часов. Это в 12,5 раз дешевле, чем писать отдельные инструкции вручную — выше мы оценивали затраты такого подхода. В итоге с документацией справляются шесть человек — а если бы мы делали инструкции вручную, потребовалось бы не меньше 13 сотрудников. После внедрения конструктора мы оценили дальнейшие трудозатраты, продолжили работу с динамической документацией, и уже через несколько месяцев система начала окупаться.
Чтобы наглядно показать динамику затрат с растущим числом конфигураций, мы построили график. Красная область — относительная стоимость одного документа; фиолетовая — объем сгенерированных документов. Всплеск в начале — этап разработки самой системы, разовая затратная часть. Далее — уже только доработки. Стоимость одного документа со временем и увеличением количества уникальных конфигураций остается низкой.
Обобщив свой опыт, мы пришли к условиям, которые обеспечат рентабельность внедрения конструктора:
Конфигураций продуктов действительно много.
По инструкциям будут собирать крупные партии продуктов — иначе создание автоматизированной документации просто не успеет окупиться.
Важно выйти на высокую скорость подготовки документации.
Есть кому изначально вложиться в разработку системы автоматизации.
Если они не соблюдены — проще написать документацию вручную.
Как внедрить динамическую документацию
Я обобщил наш опыт и подготовил список действий, которые помогут вам определить актуальность динамической документации в своей компании и внедрить ее.
Оценка текущих продуктов и документации. Проанализируйте все свои продукты на количество конфигураций, а инструкции — на вариативные и повторяемые элементы. Чем их больше, тем большую пользу в перспективе может принести динамическая документация. Попробуйте построить свой график экономической целесообразности, подобный нашему, что частично приведен выше.
Разработка и настройка рабочих файлов. Соберите максимально полные инструкции по продукту на «атомарном» уровне, выделите в каждой постоянные части, вариативные параметры и соответствующие им переменные части. Соберите список всех конфигураций продукта. В нем важно учесть абсолютно все возможные конфигурации продукта, а не только те, что востребованы в данный момент. В противном случае, если редкая конфигурация все-таки всплывет на производстве, у вас не будет подходящей инструкции.
Поддержка данных конструктора в актуальном состоянии. Конфигурации продуктов могут меняться со временем. Технологи могут дорабатывать процессы сборки для увеличения эффективности. Динамическая документация должна непрерывно и быстро адаптироваться к обновлениям контента — как «мегаинструкции», так и списка конфигураций. Существенных вложений она требует только на старте, поддерживать же ее намного дешевле.
Как оценить успешность внедрения
В долгосрочной перспективе, с ростом числа инструкций, стоимость разработки каждой отдельной инструкции постепенно уменьшается, как примерно показано на графике выше, и компания экономит деньги. Для пользователей инструкции положительная динамика также будет очевидна:
Уменьшается время на сборку и другие описанные процессы при переходе от общих инструкций к пошаговым.
Количество ошибок также уменьшается, поскольку пользователям не нужно предварительно вычленять нужную информацию.
Новые сотрудники быстрее проходят онбординг, так как адаптироваться к пошаговым инструкциям легче.
Есть преимущества и со стороны технических писателей. Они не готовят каждый документ вручную — инструкции автоматически собирает конструктор, точно копируя указанные элементы. Поэтому число случайных ошибок уменьшается. Не стоит рассчитывать, что динамическая документация упростит работу техписов: «атомарное» разбиение контента, сложение их в связный текст и другие этапы работы весьма требовательны. Но в конечном счете ваше время будет потрачено гораздо эффективней.
Хотите стать частью команды технических писателей YADRO? У нас есть вакансия.