Работая над книгой по инженерным практикам, я решил пообщаться с экспертами из индустрии, чтобы понять, что происходит в "полях", особенно в интересных областях.
Поэтому сегодня вы увидите рассказ о том, как инженерные практики упрощают работу с технической документацией.
Сегодня в нашей "текстовой студии" Наталья Павликова, руководитель отдела технической документации.
Поэтому сегодня вы увидите рассказ о том, как инженерные практики упрощают работу с технической документацией.
Сегодня в нашей "текстовой студии" Наталья Павликова, руководитель отдела технической документации.
Петр:
Наташа, здравствуй! Расскажи немного о себе, где ты сейчас, чем занимаешься?
Наталья:
Привет! Меня зовут Наталья, я руководитель отдела технической документации в компании Yadro. Наша компания занимается разработкой и выпуском большого количества аппаратно-программных продуктов: серверов, СХД, коммутаторов, клиентских устройств – планшетов, ноутбуков.
Мой отдел занимается разработкой и публикацией документации. Наши основные выходные форматы – HTML и PDF, также мы умеем выпускать PDF в схеме CMYK, что делает их пригодными для печати в типографии. В нашей зоне ответственности также находится подготовка документации для печати, которую мы кладем в комплекты поставки нашего оборудования.
Петр:
Супер! Спасибо.
В 2024 году я крайне редко вижу, чтобы команда технических писателей занималась печатной документацией. Обычно все сводится к тому, чтобы выкатить документацию на внешний, либо на внутренний портал, если это внутренняя документация.
Расскажи, пожалуйста, более детально про твою команду.
Наталья:
У нас большой отдел – 40 человек, и достаточно простая иерархическая структура – в отделе 12 направлений, в каждом из которых есть руководитель, полностью отвечающий за функцию данного направления. Каждое направление относится к определенному бизнес-процессу или продукту.
Одно из направлений – DocOps. Оно состоит из бекенд- и фронтенд-разработчиков, которые создают наши порталы, тестировщика, а также собственно docops-инженеров, занимающихся автоматизацией бизнес-процессов, связанных с документацией. Fun fact, именно у нашего отдела один из самых развесистых CI/CD пайплайнов в компании.
Петр:
Расскажи про автоматизацию? Что именно вы используете? Из чего генерируется документация?
Наталья:
В качестве основного решения мы используем Oxygen и связанные инструменты. Основным внутренним форматом для исходников документации мы выбрали DITA. Исходники документации храним в Bitbucket. Выходные HTML и PDF форматы мы генерируем через Oxygen Publishing Engine, на вход подаем dita и стили для кастомизации внешнего вида. Для разработки писатели используют специализированный IDE – Oxygen XML Editor, для обратной связи – Oxygen Feedback.
Если нам необходимо привлечь к разработке документации эксперта, который не знаком с dita, мы используем Oxygen XML Web Author - он предоставляет WYSYWYG-редактор в веб-интерфейсе для работы с исходниками.
У нас реализована двухэтапная вычитка. После окончания работы над черновиком писатель публикует документ на персональном инстансе докпортала, поднятом на отдельном порте. Такие инстансы есть у каждого писателя. На них мы производим первичную вычитку и проверку внутри отдела. Далее, после прохождения первого этапа, писатель публикует документ на stage-среде, где производится второй этап вычитки с привлечением внешних, относительно команды технических писателей, экспертов. После финальной вычитки документ публикуется на проде.
Если говорить именно про автоматизированную сборку документации, то у нас настроена работа с большим количеством источников:
Когда мы выстраиваем процесс автогенерируемой документации, мы стараемся сделать так, чтобы одним из артефактов билда приложения стали исходники документации. Далее мы цепляемся к какому-то событию в релизном цикле команды – например, к nightly-билду или к мажорному релизному билду. Это событие триггерит запуск уже нашего пайплайна, который принимает на вход исходники и публикует документацию в выходных форматах. При этом мы конвертируем форматы в dita в момент сборки, а не заставляем команды разработки переезжать на dita. Мы поддерживаем основные lightweight-форматы, такие как markdown, asciidoc, reStructuredText , xml, confluence-html. Это несколько усложняет нам жизнь, но существенно облегчает старт публикации документации командам разработки.
Петр:
Ого. Отмечу факт того, что для писателей у вас поднимается личный инстанс портала, на котором проверяется документация. Во многих компаниях нет такого даже для тестировщиков, которым необходимо проверять новые версии приложения. Скажу честно, это здорово.
Наталья:
Спасибо :)
Могу рассказать еще один кейс: недавно мы автоматизировали создание сборочной документации для высоковариативных конфигураций. Представь себе сборщика серверов. Вариантов сборки изделия может быть очень много, они всегда разные. В рамках одного продукта счет идет на тысячи возможных конфигураций. Например, разное количество процессоров, разное количество плат памяти и так далее. Если писать один большой документ – сборщик запутается, так как ему потребуется проанализировать набор комплектующих, который ему выдали и понять, какая именно конфигурация предполагается. Такая работа требует вдумчивого изучения документации. Учитывая тот факт, что среднее время сборки одного сервера занимает 40 минут, это невозможно. Поэтому мы реализовали генерацию документации на основании спецификации конкретного заказа, с конкретной конфигурацией устройства. Это потребовало интеграции с 1С:ERP и другими системами, но получилось в итоге здорово.
Петр:
Хороший пример поддержки эффективности работы платформенной командой. Интересно то, что компания занимается не только разработкой софта, но и производством hardware, что на порядок сложнее.
Если говорить про software, у вас в отделе уже есть определенная техническая база - бэкенд и фронтенд для порталов, скрипты, архитектура и инфраструктура по автоматизации работы с документами. И тут возникает резонный вопрос: работает ли руководитель отдела документирования с техническим долгом?
Наталья:
Да, конечно. Я понимаю, что техническая составляющая поддерживает работу наших писателей, помогает им выполнять свои задачи.
В начале года мы с инженерной командой DocOps собрали все задачи, которые составляли наш технический долг. Список получился достаточно внушительный и разноплановый: параллельные сборки документов, контейнеризация наших приложений и повышение их отказоустойчивости, оптимизация скриптов и Jenkinsfile-ов, оптимизация архитектуры и рефакторинг. По результатам первого квартала можно сказать, что мы потратили примерно 50% от производительности команды DocOps на решение этих задач. К сожалению, для того, чтобы выполнить все поставленные нами цели, этого времени оказалось недостаточно, поэтому мы продолжаем выделять на них время и в Q2.
Петр:
Задам, возможно, сложный вопрос - какой эффект можно получить от ваших инвестиций? Давай рассмотрим в диапазоне двух лет, обычно на нем смотрят возврат денег и профит.
Поскольку большая часть ваших задач касается непосредственно задач писателей, например,распараллеливание генерации документов, уменьшение времени на одну генерацию, и так далее, можно грубо оценить эффект в размере 5% экономии времени всех писателей. Давай попробуем посчитать в деньгах затраты и эффект как экономию 5% от зарплатного фонда.
Наталья:
Да, давай попробуем посчитать по такой формуле. 50% производительности направления DocOps за Q1 в пересчете на ФОТ составит примерно 1.5 млн рублей, которые мы инвестировали на погашение технического долга. Рассчитывая результат инвестиций как экономию 5% от ФОТ писателей в течение 2 лет, получаем результат порядка 7 млн рублей.
Петр:
Вот! Суммарная выгода получается около 5.5 млн рублей. Это действительно здорово. Учитывая, что вы планируете рост численности отдела еще на 50% к концу года, эффект будет больше.
Тут я обращу внимание на то, что многие проблемы могут быть незаметны прямо сейчас, с текущим количеством сотрудников, генерируемых документов, количеством порталов. Но при увеличении может случится коллапс и могут начаться простои либо долгое ожидание.
Наталья:
Да, все верно. Именно поэтому в начале года, в рамках оценки беклога задач в нашей инженерной команде, мы выделили достаточно много времени, делая большую часть задач, так сказать, со стратегическим уклоном, на будущее.
Петр:
Я поддерживаю такие решения. Необходимые вложения на текущий момент достаточно малы. Если делать это потом, они могут увеличиться в разы или даже на порядки.
Один из последних вопросов, который я хочу задать – какие есть планы развития отдела в этом году, или может дальше? Если есть что-то по инженерным практикам или технике, мне было бы очень интересно это услышать:)
Наталья:
Мой фокус на ближайшее время это задачи по people-менеджменту: работа с планами развития каждого сотрудника моего отдела и поддержка глобальных изменений в процессах, которые сейчас происходят в компании.
Говоря про инженерные практики, фокус будет на автоматизации новых бизнес-процессов и развитии имеющихся принципов и подходов. Также стоит отметить, что у нас на текущий момент достаточно хорошая инженерная база, в том числе процессы, практики, инфраструктура и код.
Петр:
Тут я с тобой соглашусь. Я все еще под впечатлением от того, что писатель может поднять себе приватный инстанс портала и использовать его для вычитки.
Наталья:
Да, поэтому мы будем поддерживать текущие решения, и понемногу их развивать – шлифовать что есть и повышать уровень автоматизации.
Петр:
Звучит вполне резонно.
Спасибо тебе за интервью, мне было очень интересно послушать про то, как работают с технической документацией с использованием инженерных подходов. Это очень здорово!
Наталья:
Спасибо, что позвал :)
Наташа, здравствуй! Расскажи немного о себе, где ты сейчас, чем занимаешься?
Наталья:
Привет! Меня зовут Наталья, я руководитель отдела технической документации в компании Yadro. Наша компания занимается разработкой и выпуском большого количества аппаратно-программных продуктов: серверов, СХД, коммутаторов, клиентских устройств – планшетов, ноутбуков.
Мой отдел занимается разработкой и публикацией документации. Наши основные выходные форматы – HTML и PDF, также мы умеем выпускать PDF в схеме CMYK, что делает их пригодными для печати в типографии. В нашей зоне ответственности также находится подготовка документации для печати, которую мы кладем в комплекты поставки нашего оборудования.
Петр:
Супер! Спасибо.
В 2024 году я крайне редко вижу, чтобы команда технических писателей занималась печатной документацией. Обычно все сводится к тому, чтобы выкатить документацию на внешний, либо на внутренний портал, если это внутренняя документация.
Расскажи, пожалуйста, более детально про твою команду.
Наталья:
У нас большой отдел – 40 человек, и достаточно простая иерархическая структура – в отделе 12 направлений, в каждом из которых есть руководитель, полностью отвечающий за функцию данного направления. Каждое направление относится к определенному бизнес-процессу или продукту.
Одно из направлений – DocOps. Оно состоит из бекенд- и фронтенд-разработчиков, которые создают наши порталы, тестировщика, а также собственно docops-инженеров, занимающихся автоматизацией бизнес-процессов, связанных с документацией. Fun fact, именно у нашего отдела один из самых развесистых CI/CD пайплайнов в компании.
Петр:
Расскажи про автоматизацию? Что именно вы используете? Из чего генерируется документация?
Наталья:
В качестве основного решения мы используем Oxygen и связанные инструменты. Основным внутренним форматом для исходников документации мы выбрали DITA. Исходники документации храним в Bitbucket. Выходные HTML и PDF форматы мы генерируем через Oxygen Publishing Engine, на вход подаем dita и стили для кастомизации внешнего вида. Для разработки писатели используют специализированный IDE – Oxygen XML Editor, для обратной связи – Oxygen Feedback.
Если нам необходимо привлечь к разработке документации эксперта, который не знаком с dita, мы используем Oxygen XML Web Author - он предоставляет WYSYWYG-редактор в веб-интерфейсе для работы с исходниками.
У нас реализована двухэтапная вычитка. После окончания работы над черновиком писатель публикует документ на персональном инстансе докпортала, поднятом на отдельном порте. Такие инстансы есть у каждого писателя. На них мы производим первичную вычитку и проверку внутри отдела. Далее, после прохождения первого этапа, писатель публикует документ на stage-среде, где производится второй этап вычитки с привлечением внешних, относительно команды технических писателей, экспертов. После финальной вычитки документ публикуется на проде.
Если говорить именно про автоматизированную сборку документации, то у нас настроена работа с большим количеством источников:
- комментарии в исходном коде;
- Jira-тикеты;
- страницы в Confluence;
- readme-файлы в репозиториях;
- автотесты.
Когда мы выстраиваем процесс автогенерируемой документации, мы стараемся сделать так, чтобы одним из артефактов билда приложения стали исходники документации. Далее мы цепляемся к какому-то событию в релизном цикле команды – например, к nightly-билду или к мажорному релизному билду. Это событие триггерит запуск уже нашего пайплайна, который принимает на вход исходники и публикует документацию в выходных форматах. При этом мы конвертируем форматы в dita в момент сборки, а не заставляем команды разработки переезжать на dita. Мы поддерживаем основные lightweight-форматы, такие как markdown, asciidoc, reStructuredText , xml, confluence-html. Это несколько усложняет нам жизнь, но существенно облегчает старт публикации документации командам разработки.
Петр:
Ого. Отмечу факт того, что для писателей у вас поднимается личный инстанс портала, на котором проверяется документация. Во многих компаниях нет такого даже для тестировщиков, которым необходимо проверять новые версии приложения. Скажу честно, это здорово.
Наталья:
Спасибо :)
Могу рассказать еще один кейс: недавно мы автоматизировали создание сборочной документации для высоковариативных конфигураций. Представь себе сборщика серверов. Вариантов сборки изделия может быть очень много, они всегда разные. В рамках одного продукта счет идет на тысячи возможных конфигураций. Например, разное количество процессоров, разное количество плат памяти и так далее. Если писать один большой документ – сборщик запутается, так как ему потребуется проанализировать набор комплектующих, который ему выдали и понять, какая именно конфигурация предполагается. Такая работа требует вдумчивого изучения документации. Учитывая тот факт, что среднее время сборки одного сервера занимает 40 минут, это невозможно. Поэтому мы реализовали генерацию документации на основании спецификации конкретного заказа, с конкретной конфигурацией устройства. Это потребовало интеграции с 1С:ERP и другими системами, но получилось в итоге здорово.
Петр:
Хороший пример поддержки эффективности работы платформенной командой. Интересно то, что компания занимается не только разработкой софта, но и производством hardware, что на порядок сложнее.
Если говорить про software, у вас в отделе уже есть определенная техническая база - бэкенд и фронтенд для порталов, скрипты, архитектура и инфраструктура по автоматизации работы с документами. И тут возникает резонный вопрос: работает ли руководитель отдела документирования с техническим долгом?
Наталья:
Да, конечно. Я понимаю, что техническая составляющая поддерживает работу наших писателей, помогает им выполнять свои задачи.
В начале года мы с инженерной командой DocOps собрали все задачи, которые составляли наш технический долг. Список получился достаточно внушительный и разноплановый: параллельные сборки документов, контейнеризация наших приложений и повышение их отказоустойчивости, оптимизация скриптов и Jenkinsfile-ов, оптимизация архитектуры и рефакторинг. По результатам первого квартала можно сказать, что мы потратили примерно 50% от производительности команды DocOps на решение этих задач. К сожалению, для того, чтобы выполнить все поставленные нами цели, этого времени оказалось недостаточно, поэтому мы продолжаем выделять на них время и в Q2.
Петр:
Задам, возможно, сложный вопрос - какой эффект можно получить от ваших инвестиций? Давай рассмотрим в диапазоне двух лет, обычно на нем смотрят возврат денег и профит.
Поскольку большая часть ваших задач касается непосредственно задач писателей, например,распараллеливание генерации документов, уменьшение времени на одну генерацию, и так далее, можно грубо оценить эффект в размере 5% экономии времени всех писателей. Давай попробуем посчитать в деньгах затраты и эффект как экономию 5% от зарплатного фонда.
Наталья:
Да, давай попробуем посчитать по такой формуле. 50% производительности направления DocOps за Q1 в пересчете на ФОТ составит примерно 1.5 млн рублей, которые мы инвестировали на погашение технического долга. Рассчитывая результат инвестиций как экономию 5% от ФОТ писателей в течение 2 лет, получаем результат порядка 7 млн рублей.
Петр:
Вот! Суммарная выгода получается около 5.5 млн рублей. Это действительно здорово. Учитывая, что вы планируете рост численности отдела еще на 50% к концу года, эффект будет больше.
Тут я обращу внимание на то, что многие проблемы могут быть незаметны прямо сейчас, с текущим количеством сотрудников, генерируемых документов, количеством порталов. Но при увеличении может случится коллапс и могут начаться простои либо долгое ожидание.
Наталья:
Да, все верно. Именно поэтому в начале года, в рамках оценки беклога задач в нашей инженерной команде, мы выделили достаточно много времени, делая большую часть задач, так сказать, со стратегическим уклоном, на будущее.
Петр:
Я поддерживаю такие решения. Необходимые вложения на текущий момент достаточно малы. Если делать это потом, они могут увеличиться в разы или даже на порядки.
Один из последних вопросов, который я хочу задать – какие есть планы развития отдела в этом году, или может дальше? Если есть что-то по инженерным практикам или технике, мне было бы очень интересно это услышать:)
Наталья:
Мой фокус на ближайшее время это задачи по people-менеджменту: работа с планами развития каждого сотрудника моего отдела и поддержка глобальных изменений в процессах, которые сейчас происходят в компании.
Говоря про инженерные практики, фокус будет на автоматизации новых бизнес-процессов и развитии имеющихся принципов и подходов. Также стоит отметить, что у нас на текущий момент достаточно хорошая инженерная база, в том числе процессы, практики, инфраструктура и код.
Петр:
Тут я с тобой соглашусь. Я все еще под впечатлением от того, что писатель может поднять себе приватный инстанс портала и использовать его для вычитки.
Наталья:
Да, поэтому мы будем поддерживать текущие решения, и понемногу их развивать – шлифовать что есть и повышать уровень автоматизации.
Петр:
Звучит вполне резонно.
Спасибо тебе за интервью, мне было очень интересно послушать про то, как работают с технической документацией с использованием инженерных подходов. Это очень здорово!
Наталья:
Спасибо, что позвал :)
Как заключение, выскажу свои комментарии по поводу того, что мне рассказала Наталья.
Больше всего меня, честно, порадовало то, что здесь используется, я бы сказал, сильный инженерный подход:
Так же эти и другие посты вы сможете найти в моем телеграм канале: ТУГОЛУКОВ про IT.
Будем на связи и всем полной документации!
Больше всего меня, честно, порадовало то, что здесь используется, я бы сказал, сильный инженерный подход:
- Документация хранится как код;
- Используется кодогенерация (читай доко-генерация);
- Много автоматизации;
- Инфраструктура поддерживает работу команды;
- Менеджмент уделяет внимание техническому качеству, за счет чего они выигрывают в эффективности и времени выполнения задач.
Так же эти и другие посты вы сможете найти в моем телеграм канале: ТУГОЛУКОВ про IT.
Будем на связи и всем полной документации!
