Привет, Хабр! Меня зовут Роман Блинов, я ведущий технический писатель в «Цифре» — в команде по развитию платформы ZIIoT. Этот пост будет о подходе Docs-as-code для документирования разработки ПО. Пишу с прицелом на тех читателей (то есть писателей), кто этот подход пока не пробовал и по факту имеет набор файлов в Confluence, файлы формата .docx и .pdf, на поддержку, обновление и оформление которых тратится порядка 70 % времени (а хотелось бы меньше), и 101 отговорку разработчиков, чтобы не участвовать в документировании.
Сначала расскажу, с какими проблемами сталкиваются писатели до перехода на Docs-as-code, затем опишу подход в общих чертах и в конце упомяну об основной трудности его внедрения по собственному опыту и опыту коллег.
На что жалуетесь? Три боли технического писателя до внедрения Docs-as-code
1. Разработчики слабо вовлечены в процесс документирования
Документирование — неотъемлемая часть разработки программного обеспечения, и этот процесс требует участия не только технического писателя, но и разработчиков. Однако последние об этом периодически забывают или по разным причинам пытаются дистанцироваться от процесса. Такой подход недопустим. Разработчик, а равно и его руководитель, при планировании работ должны закладывать определенный объем времени на консультации с техническим писателем. Отсюда крик души технического писателя: не забывайте о нас! Работа над документами — это время и силы. Если вы хотите, чтобы все было сделано хорошо, будьте готовы посвятить немного своего времени данному процессу. Ну и еще очень поможет, если разработчик ведет свои заметки.
2. Команда документирования слабо информирована о ходе разработки
Когда система документирования встроена по формату Docs As Service, группа документирования оторвана от групп разработки и формирует документацию на основе постановок, поступающих от разработчиков. При этом группа документирования не имеет представления о ходе разработки и тех процессах, которые протекают в ее рамках. Более того, ответственные за документацию практически не владеют информацией о развитии продукта и не могут полностью отвечать за консистентность документации и ее актуальность, так как всегда есть человеческий фактор, когда кто-то кому-то банально забыл сказать, что вышел новый релиз или что-то поменялось в текущем. Документация в этом случае превращается в набор файлов в Confluence и других форматах, например, .docx и .pdf, которые постоянно приходится поддерживать, обновлять и вообще держать в адекватном состоянии.
Такой подход ведет к тому, что около 70 % времени тратится на беготню за разработчиком, оформление и переработку документов. Проще говоря, писатель сидит и раскрашивает файлы в корпоративные цвета и правит шрифты и таблицы. И только 30 % времени уходит на формирование самих документов. Согласитесь, это, мягко говоря, неэффективно, и хотелось бы поменять цифры местами. Да и некоторые вопросы остаются без ответов.
3. Нет версионности
Возможна ли версионность при существующем подходе? Что нам делать, если требуются документы на различные релизы? А как быть, если нам потребовались документы на версию продукта годовой давности (как бы смешно ни звучало, но это случай из практики)? Ответ прост: придется сидеть и искусственно старить документы: выкидывать из них новые фичи, менять картинки. Все опять сведется к нашим 70 % (а то и больше) времени на оформление.
Чем лечить будем
Чтобы избавиться от ненужных стрессов, требуется изменить образ жизни технического писателя, точнее подход к документированию. В качестве панацеи в писательской среде уже давно обсуждается и применяется система организации документирования Docs As Part Of Development Team, когда технические писатели включены в процесс разработки и подготовка документов является его неотъемлемой частью. Документация ведется в формате Docs-as-code, основанном на технологиях DevOps в разработке ПО, когда работа над документацией строится на тех же принципах, что и работа над исходным кодом, и передается заказчику в рамках аналогичных процессов.
Проще говоря, в парадигме Docs-as-code команда документирования встает на те же рельсы, что и разработчики, и применяет в своей работе тот же инструментарий и процессы, но только для разработки документации. Документация «живет» в тех же местах, что и код, и передается заказчику так же, как код.
В чем суть и преимущества этого подхода
В основе подхода лежит переиспользование инфраструктуры разработки ПО для ведения документации.
В качестве базы применяется простой текст, написанный в легкой, человекочитаемой разметке, которая остается читаемой даже в исходном виде, что значительно сближает ее с кодом. В качестве основы для хранения используется система контроля версий Git, а релиз осуществляется посредством CI в необходимом формате.
Особенности:
· Ведение документации в простом текстовом формате.
· Использование инструментария и подходов к разработке исходного кода.
Плюсы: не нужно строить отдельную инфраструктуру (она и так уже есть), легко поднимается, понятна для команды разработки.
Минусы: немного сложнее в использовании, техническим писателям без опыта разработки потребуется время, чтобы привыкнуть к процессу и освоить ряд достаточно жестких правил.
Структура разработки документации
Работа над документацией в рамках подхода Docs-as-code включает следующие элементы, повторяющие аналогичные шаги разработки:
1. Текст кода — Текст документа.
2. Система контроля версий кода — Система контроля версий документа.
3. Merge Request для код-ревью — Merge Request для вычитки документации.
4. CI для сборки кода — CI для сборки документа.
5. Code Style и релизные практики — Руководства по стилю и редакционные политики.
6. Автотесты для сборки — Автотесты для документации.
Рассмотрим каждый элемент по порядку.
Текст кода — Текст документа
В основе подхода Docs-as-code лежит легковесная разметка и простой текст. Нами был выбран язык разметки Markdown, т. к. он наиболее прост в освоении и практичен в применении. Можно сказать, что Markdown является стандартом при разработке подобной документации. Также можно применять ASCIIDoc или reStructured Text, но данные языки обладают достаточно большим набором правил, которые необходимо освоить, а также требуют специфического программного обеспечения.
Markdown не требует долгого и кропотливого изучения. Он достаточно понятен даже на уровне интуиции, и все форматирование текста в нем осуществляется при помощи простейших символов типа пробелов, табуляции и т. п. Язык поддерживает все основные способы форматирования текста, которые требуются для оформления документации: заголовки, абзацы, списки, выделение блоков текста, изображения и т. п. При этом в нем довольно ограниченный набор возможностей форматирования, что значительно снижает вероятность испортить текст и сделать его менее читаемым по сравнению с тем же MS Word, где можно перегрузить текст выделениями, некорректно его отформатировать и выполнить множество иных нежелательных действий, не говоря уже о том, что текст, отформатированный в одном шаблоне, чаще всего превращается в полную кашу в другом.
Важная особенность настройки Markdown — возможность применения шаблонов оформления текста документа, где первоначально задается шаблонный стиль, и все документы автоматически будут выходить именно в таком оформлении. Это способствует более корректной работе над документацией в команде, когда над одним документом трудится несколько человек или требуется единообразное оформление всей документации.
Для работы с текстами доступны все расширенные текстовые редакторы. В нашем случае мы применяем редактор VS Code, так как он хорошо встраивается в наш процесс интеграции и доставки обновлений, но можно использовать и другие — Atom и т. п. Кстати, один из редакторов — Typora — позволяет очень легко и быстро преобразовывать текст из двоичных форматов типа .docx в Markdown. И его использование в комбинации с VS Code помогает сильно ускорить процесс переработки документов из других форматов.
Все это позволяет значительно облегчить работу с документацией и ускорить процесс ее разработки. Кроме того, данные инструменты намного проще в работе по сравнению с файлами MS Word и т. п.
Система контроля версий кода — Система контроля версий документа
Как уже говорилось, в качестве системы хранения и контроля версий применяется Git. Особенность Git — наличие веток, посредством которых можно осуществлять контроль над тем, что было создано, отслеживать и откатывать версии, следить за актуальностью, вести совместную работу над документом и т. п.
Такой подход несколько отличается от совместного редактирования документации с использованием Sharepoint и других ресурсов. С одной стороны, скорость такой совместной работы может немного упасть, так как необходимо создавать свою версию файла, а затем осуществлять процесс слияния. То есть не получится быстро взять и набросать какой-то текст. Зато мы получаем процедуру вычитки документации — в процессе Merge Request мы можем контролировать все изменения, отклонять те, что не соответствуют, и не пускать их в основную ветку. Также мы можем увидеть буквально по каждой строке, кто и когда ее создал и изменил. Таким образом, кроме отслеживания изменений глобально по репозиторию мы можем отслеживать их в отдельных файлах.
Отдельный бонус — это возможность создания нескольких версий одного и того же документа. Без Git при наличии нескольких версий системы придется копировать документацию и управлять ими по отдельности. В Git же мы можем сделать несколько веток помимо основной и сливать только те изменения, которые нам необходимы.
Merge Request для код-ревью — Merge Request для вычитки документации
Как уже говорилось выше, для вычитки и согласования текстов документов используется система Merge Request, принятая в Git. При написании отдельного блока документации можно не сразу сливать текст в основную ветку, а создать запрос и отправить его на проверку редактору и техническому специалисту. И здесь снова необходимо подчеркнуть важность использования легковесного языка разметки, который легко читается в исходнике, когда непосредственно в Git мы можем проверить основные моменты текста, прикрепить комментарии и т. п.
CI для сборки кода — CI для сборки документа
Стоит упомянуть о процедуре сборки документа. После создания готового документа возникает необходимость конвертации документа в какой-либо единый формат, который в дальнейшем может быть передан заказчику, и т. п.
При подходе Docs-as-сode документация хранится непосредственно в репозитории с исходным кодом проекта, читаема, как и все материалы в Git, и передается заинтересованному лицу вместе с исходным кодом проекта. Все материалы при таком подходе соответствуют той версии ПО, которая передается заказчику, и автоматически являются актуальными, что значительно снижает временные затраты на актуализацию документов.
В случае же, когда заказчику по каким-либо причинам требуется документация в отчуждаемом формате — .docx, .pdf и т. д., наш подход позволяет сгенерировать необходимый документ с использованием утилиты под названием Pandoc. Данный инструмент позволяет выполнять конвертацию документов из Markdown и обратно в большинство используемых форматов. На выходе мы можем создать практически любой файл и передать его либо разместить в системе управления документацией, которой пользуется заказчик.
Важный аспект при этом — возможность конвертации документа в определенный корпоративный шаблон, когда мы получаем не просто неоформленный документ, а практически полностью готовый к передаче документ, который требует небольшой доработки, например корректировки таблиц. Но даже при таком состоянии дел работа над отчуждаемой версией документа займет в разы меньше времени, чем копирование и форматирование целиком.
Code style и релизные практики — Руководства по стилю и редакционные политики
Markdown поддерживает настраиваемые шаблоны оформления документации, и в данном случае мы можем настроить практически любое правило — как для оформления документа, так и для его содержания. Для этого требуется достаточно подробно проработанное руководство по стилю оформления документации, которое будет максимально адаптировано для используемого подхода и будет составлено исходя из лучших практик его применения. Мы сейчас как раз дорабатываем такой документ у себя, чтобы он был более приспособлен к использованию в рамках подхода Docs-as-code. Важно также подготовить достаточно удобный глоссарий, содержащий основные терминологические единицы, применяемые в рамках разрабатываемого ПО.
Автотесты для сборки — Автотесты для документации
Необходимо упомянуть и о возможности автотестов документации. Так, наш подход позволяет осуществлять следующие варианты проверки документа:
· линтинг разметки и орфографии;
· валидность ссылок;
· соответствие глоссарию.
Отдельные вопросы локализации документации
Для локализации документов у нас применяется открытое ПО Weblate, которое интегрируется с Git и позволяет выполнять локализацию как обычных текстовых файлов, так и json-файлов и др. Важно, что данное ПО работает по системе «память перевода» и позволяет автоматизировать и ускорить процесс перевода за счет накопления базы готовых сегментов текста, которые потом программными средствами вставляются в текст. Это весьма актуально для технических текстов, где содержится большой объем повторяющихся блоков и наименований.
Ну и не без ложечки дегтя
«Классно!» — скажете вы и будете бесконечно правы. Удобный модный формат с автоматизацией большинства функций обработки текста, быстрый процесс передачи и доставки заказчику, версионность — что может быть лучше?! Мы уже победили. Надо только все корректно оформить.
Не тут-то было. Мы общались с представителями разных компаний, которые уже применяют Docs-as-code или только внедряют его в каждодневную практику, и конечно же, все они сталкивались в процессе внедрения с различными трудностями. Мы не исключение. Если суммировать. то можно прийти к пониманию, что трудность всего одна: для перехода на Docs-as-code нужно дозреть.
Да, все классно: быстро, удобно и легко. Но Docs-as-code — это не просто система документации, это нечто более близкое к философии, которая требует в первую очередь строгой внутренней дисциплины, выстроенных бизнес-процессов и, главное, желания улучшить жизнь самим себе. А для этого требуется, как сейчас модно говорить, выйти из зоны комфорта и встать на путь постоянного развития.
С одной стороны, техническому писателю удобно работать по старой системе: сидишь себе спокойно, правишь рисунки в тексте — и время идет, рабочее, между прочим, и зарплата капает. А тут брось все это, изучи что-то новое, да еще освободи 70 % своего рабочего времени. И чем потом это время занимать? Конечно, работой над качеством документации, а это сложнее. С другой стороны, есть разработчик, он всегда занят, у него тысяча задач. Когда ему заниматься рисованием схем и объяснением писателю, а что же, собственно, его сервис делает и как. Конечно, времени нет. А еще есть руководитель проекта, которому в рамках нового подхода придется придумывать, как и когда встроить документирование в процесс работы.
Кроме того, у многих компаний, растущих методом слияний и поглощений, есть наследство из практиков старой закалки, которым требуется время на адаптацию к новой корпоративной культуре и которые не всегда легко принимают новые правила.
Создание и развитие хорошего продукта всегда идет параллельно с развитием команды, его создающей, а это включает также улучшение процессов разработки и документирования. Подход Docs-as-code этому способствует, и наша команда разработки ZIIoT зашла достаточно далеко в его применении, чтобы оценить все плюсы. Рапортовать о завершении этого пути пока рано, но мы работаем над этим.
Комментарии (42)
ophil
17.09.2021 14:21Странно, в статье ни разу не встретилось слово гитхаб. Всё перечисленное там уже есть, плюс gitpages, wiki, issues, discussions, gists. И тысячи проектов с примерами вполне актуальной документации и налаженной работы команд.
RomanBlinov Автор
17.09.2021 14:38Гитхаб - это все-таки хостинг для совместной разработки, а у нас она своя. Гит используется как система контроля версий, а все остальное уже сугубо корпоративное.
Mur466
18.09.2021 03:01+1Подход напоминает сисадмина, который уже знает, что надо регулярно делать бекап, но не знает, что также его надо регулярно проверять (восстанавливать) .
Концентрация на улучшении процесса написания, а не использования документации.
Если цель ведения документации — спихнуть что-то заказчику, чтобы формально закрыть договор, то подход имеет право на жизнь.
Если документация пишется, чтобы ею пользовались, то главным критерием улучшений должно быть удобство использования и качество содержания. Отсюда вытекает confluence или другая продвинутая wiki с мощным поиском, плагинами для диаграмм и прочими плюшками, кстати версионирование страниц там есть и без гита. А также необходимо регулярное чтение документации не только самим писателем или разработчиком темы, но и аналитиком или другим человеком "со стороны", который вдумчиво будет пытаться сопоставить набор слов с тем, что они в реальности описывают, задавать вопросы и требовать уточнений.
Наверное merge request имеет право на жизнь, но это только если трудится целая группа писателей.
Программисты должны непременно быть вовлечены, но гит использовать для этого вовсе не обязательно.
Главная проблема технической документации — ее бесполезность в силу формального подхода к написанию и быстрого "протухания". Указанный в статье подход никак с этими проблемами не борется. Похоже на карго-культ методик и инструментов разработки.
RomanBlinov Автор
18.09.2021 19:46Добрый вечер. Подход docops никогда не ставил целью спихивать что-либо заказчикам или как-то концентрироваться на качестве отдельных документов. Плохой документ может создаваться и ворде, и в конфлюенс и в гите. Суть данного подхода в автоматизации тех практик, которые сейчас практически полностью ручные: 1. Формат документа - простая читаемая разметка; 2. Использование для написания техник аналогичных техникам разработки, 3. Отсутствие необходимости актуализации доков в 100 источниках (конфлюенс хорош, когда он один, а что делать если аналогичная документация развернута у заказчиков, и каждый из них просит тот формат, что ему удобен? На каждом ресурсе каждый из нескольких десятков доков обновлять? Как-то минимально продуктивно), единый процесс доставки, когда заказчик получает новую версию документа с новой версией сервиса, и т.п. В этом суть docs as code.
XVlady5
18.09.2021 19:47С одной стороны задачу чтения в удобном виде - давно решили без конфлю. С другой - версионность и отчуждаемость в конфлю есть, но это ад. С третьей - читать с карандашом и отправлять потом вопросы и правки - как-то удобнее, чем в реквесте.
Для себя нашёл один выход - писать в md, в ci лить в конфлю, обсуждать в ней же, результат фиксить в md/git/реквест на слияние.
Кстати, графики тоже хочется в текст. Пока получилось только диаграммы последовательностей туда утащить.
RomanBlinov Автор
18.09.2021 19:51Интересная мысль, но честно говоря, не очень себе представляю, как поженить md и конфлюенс? Или там все-таки отображается только ссылка?
XVlady5
20.09.2021 19:32У confluence неплохой api. А нашего экземпляра нет возможности хранить md, поэтому ci дополняется cd, генерящий html из md с рядом правок под извращения confluence и обновляет страницы
RomanBlinov Автор
20.09.2021 21:38Спасибо. Интересно, надо слазить внутрь конфы. Честно говоря, как-то не задавался такими способами.
kRosis
19.09.2021 21:28+1А что, собственно, мешает переместить бегущего позади писателя на остриё разработки?
Поясню, из личного опыта. Вот обсуждаем с командой новый функционал, вместе с нами сидит писатель и записывает обсуждение. Если у него возникают какие-то вопросы - он может их задать. Далее пишется документация, параллельно создаются эпики, таски и т.д. И разработчики создают тот функционал, который описан в wiki, не больше не меньше. Фактически краткое описание фич в задачах, развёрнутое в wiki и если возникают нестыковки, то люди обращаются к wiki, а потом смотрят в код. Оговорюсь, что наш писатель находится в контексте продукта.
Таким образом в wiki всегда актуальная и наиболее полная информация.
Для вики полно хороших инструментов confluence, gitlab wiki, etc. Которые имею page history. В readme.md описывается узкая информация по конкретному приложению.
RomanBlinov Автор
19.09.2021 21:37Добрый вечер! На самом деле ничто не мешает. просто Ваша модель документирования опирается на другой инструмент и больше соответствует docs as service - это так же рабочая модель, и так же применяется. Просто если у Вас в процессе какого-либо этапа разработки возникнет изменение или дополнение, то пока вы не посадите техписа рядом, он не узнает об этом, а когда до него дойдет постановка, пока он разберется, пока напишет и донесет до команды. Такая модель хорошо работает, когда у вас идеально отработан процесс постановки задач писателям, а если нет? А как быть, когда ваш продукт развивается на глазах и когда новые фичи становятся базовыми сервисами в течение одного-двух дней, ждать митинга с писателем? Docs as code работает, и когда команда не успела ему сообщить, банальные уведомления приходят.
kRosis
19.09.2021 23:15+1А как быть, когда ваш продукт развивается на глазах и когда новые фичи становятся базовыми сервисами в течение одного-двух дней, ждать митинга с писателем?
Пилили стартап в таком стиле, вроде никаких проблем замечено не было.
Такая модель хорошо работает, когда у вас идеально отработан процесс постановки задач писателям, а если нет?
Не очень понимаю словосочетания "процесс постановки задач писателям", какие задачи им требуется ставить?
Наш подход работает хорошо отчасти потому что на 1 команду 1 писатель. Как организовать работу одному писателю для 2 и более команд - вопрос хороший. Из предположений - проводить митинги не в одно время, чтоб писатель мог присутствовать на всех.
RomanBlinov Автор
20.09.2021 08:36Да, согласен, но тут есть проблема в первую очередь в количестве задач. Одна команда - один писатель, это, конечно, хорошо, но когда писателей 10, а команд вдвое больше? И количество параллельно разрабатываемых сервисов более 200, становится просто нереально проводить по каждому апдейту встречи и все обсуждать (лучше автоматизировать эти процессы, а встречи оставить как важные вспомогательные элементы взаимодействия).
Плюс есть еще один очень важный момент - клиенты, мы разрабатываем документацию для конкретных клиентских решений, которые хоть немножко, но отличаются, и требуют дополнительных доработок, а кроме того клиентская документация реализована в различных форматах, начиная от банальных вордовских файлов и заканчивая вики- и html-версиями. Тут тоже образуется значительный пул доработок, которые в определенный момент требуют фактически перестройки всей страницы на портале у заказчика, и это потребность в огромном количестве времени.
Поэтому, на мой взгляд, все-таки лучше автоматизировать максимум того, что можно автоматизировать, чтобы эффективнее использовать труд писательской команды, не заставляя их мотаться по бесконечным встречам и бесконечно перерисовывать шрифты и картинки в документах.
gmtd
20.09.2021 10:03+1На этапе альфа и бетта девелопмента docs-as-code очень удобна. При меняющемся коде отдельная документация быстро устаревает, у разработчиков пропадает мотивация ее поддерживать (отнимает много времени и усилий)
Javadoc (странно, что он ни разу не упомянут) является в данном случае для меня идеалом данного подхода, и за 25 лет использования доказал свою практичность.
Однако проблема в средствах генерации для других систем.
Взять популярные фреймворки - Vue.js например. Есть отдельные индивидуальные попытки создать jsdoc и прочее, но хорошего качественного средства так почему-то никто и не сделал. А жаль. Это очень нужная штука даже для команды из одного-двух программеров, не говоря уж больших группах разработчиков.
AZaz1
21.09.2021 21:04+2все попытки использовать jsdocs и подобные с треском провалились из-за долгих танцев с бубном по форматированию всего этого описания и необходимости помнить сущности связанные с форматированием этих описаний
самый удобный подход предполагающий наличие хоть како-либо документации - написание readme.md, во всех местах требующих пояснений
конечно же выделенный Пушкин в команде - это супер, но не все готовы содержать технических писателей особенно если продукт не является публичным
ivanych
27.09.2021 09:42Я не понял, как вы предлагаете потом эту документацию читать. Нужно скачивать исходники и искать по ним куски документации? Это же крайне неудобно.
Удобно - это Конфлюенс, всегда доступный, с поиском, оглавлением и прочими плюшками.
Вы мельком упомянули некий pandoc - что это? Какой- то инструмент для извлечения документации из кода и помещения извлечённой документации в Конфлюенс? Вы именно так делаете? В CI автоматически запускается экспорт в Конфлюенс?
Если экспорт в Конфлюенс не происходит - как предлагается читать документацию?
RomanBlinov Автор
27.09.2021 11:38Добрый день! Подробное рассмотрение вопроса публикации документации в данном подходе просто не вошло в статью ввиду значительного объема материала. Если вкратце, то подход docs as code предполагает, что документация готовится для размещения онлайн, и у нас имеется соответствующий инструмент, который собирает материалы в ветках гита и публикует их, после чего материалы доступны заказчику и другим заинтересованным лицам. С самого ресурса документация может быть скачана в необходимом формате, для этого как-раз и используется утилита Pandoc, которая конвертирует документы в те форматы, которые необходимы и обладает достаточно широкими способностями для настройки, например, позволяет применить для оформления документа корпоративный шаблон.
В случае же с доставкой документа непосредственно заказчику, документ собирается в соответствии с теми же процедурами, с которыми происходит сборка образа программы и т.п. вещи. При этом заказчику нет нужды читать документ, содержащий информацию по всем сервисам продукта, которые ему не поставляются, он получает только документ, который соответствует тем сервисам, которые развернуты у него. А дальше документ может уже передаваться в той форме, которая необходима самому заказчику, например, может быть экспортирована в ворд или предоставлена в виде Html, или размещена в том же конфлюенс и т.п.
Что же касается вопроса использования конфлюенс - тут есть базовые проблемя для размещения документации, которые никто не решил: 1. Доступ к документам (размещать у себя и давать доступ для заказчика? Не очень разумный вариант, т.к. в этом случае вы пустите в свою базу знаний сторонних лиц, которым там, может быть, и незачем находиться); 2. Размещение документов на ресурсах заказчика ( а если заказчик не пользуется конфлюенс? Экспорт из него ну вот никак нельзя назвать нормальным - это весьма проблемный документ, который требует очень глубокой проверки и доработки, т.к. из него часто банально пропадают изображения и схемы, а кроме этого такой документ невозможно оформить в соответствии с требованиями заказчика, например, в его корпоративном шаблоне. Также, заказчик вполне может применять в своей работе какую-нибудь иную вики-базу, x-wiki например, которая тоже весьма проблематично взаимодействует с конфлюенсом. А наш подход позволяет создать документ в таком формате и разметке, который является универсальным и легко может быть подготовлен для импорта в системы заказчика, либо просто может быть передан через CI.
ivanych
27.09.2021 19:45Простите, но без рассмотрения вопроса чтения вопрос написания становится бессмысленным. Вот написал я документацию в коде - иии? Как читать-то?
Вы какой-то обтекаемый ответ даёте - "ну как там надо будет заказчику в таком формате и будет".
Давайте рассмотрим ситуацию без абстрактного заказчика. Пусть у нас есть только мы сами. Я написал документацию, коллеги хотят (и должны) прочитать. Как предлагаете поступить? Как сами поступаете со своей документацией?
RomanBlinov Автор
28.09.2021 07:21У нас она собирается на соответствующем ресурсе в сети, к которому настраивается доступ, и где ее можно в любой момент посмотреть и получить. Наши документы в открытом доступе не лежат, но в качестве примера можно привести такую страничку - https://developers.xsolla.com/subscriptions-api/. Принцип аналогичный.
ivanych
28.09.2021 09:20Абажжите... по ссылке находится спецификация API и это совсем не то же самое, что документация. Спека - это один простой текстовый файл, плюс скрипт на яваскрипте, который его рендерит. Там и извлечения-то документации никакого вообще нет - спека просто доступна по урлу как отдельный ендпойт API.
Вы всё это время говорили о спеках API что ли?
Я-то подразумевал развесистую многостраничную документацию. Ну, вот как в Конфлюенсе - разделы, страницы, ссылки между страницами. Такое у вас делается? Какими средствами? Где, если не в Конфлюенсе, такую документацию читать?
RomanBlinov Автор
28.09.2021 10:07Нет, это лишь пример того, как документация может быть организована. Смысл данного решения - организация документации по тем же принципам, что и исходный код и связанные с ним элементы, так чтобы документы можно было собрать и отобразить в каком-либо одном месте или выгрузить и передать.
Если перейдете на другие страницы ссылки, там будут и другие документы. И все они многостраничные с перекрестными ссылками, рисунками, схемами и т.п.
А что касается возможности извлечения документов, это уже вопрос индивидуальной настройки ресурса, наш настроен и позволяет выгрузить документ.
amarao
Во всём этом я вижу два тезиса:
Документация в гите
Ревью документации.
Это работает, но только для операционных вопросов. От сгнивания документации это не спасает. От соответствия документации и кода это не спасает. Причина? Когда код ломается, мы это видим. Когда документация сгнивает (перестаёт быть актуальной или даже противоречит происходящему) мы это замечаем потом. Когда нибудь.
А вот как увидеть, что документация сгнила? Ручное тестирование документации? Это ещё хуже, чем ручное тестирование продукта. Где наш AI, который может вычитывать документацию и говорить, что содержимое не соответствует происходящему в окружающем мире?
RomanBlinov Автор
На самом деле, даже те два тезиса, что приведены, - это уже многое. Проведение корректного ревью и возможность совместить процесс передачи кода с передачей документации заказчику - это значительное упрощение работы.
Что же касается актуализации, все-таки это вопрос в большей степени к дисциплине разработки, планированию и выстраиванию процессов. Если документирование, в принципе, отсутствует в планировании работ по новой фиче или обновлению старой, то да, вряд ли мы сможем все отследить вовремя, если же работы запланированы и настроен процесс оповещения группы документирования, то проблем возникать не должно.
Ну, и чисто технически, как понять, что документация сгнила - если она обновлена год назад, а последние обновления запушены вчера, то, скорее всего, она уже никому не нужна. )))
А, в целом, docops скорее способ автоматизировать те процессы обработки и доставки документации, которые мы сейчас выполняем вручную, ну, и приблизить команду писателей к команде разработки.
amarao
Если бы программисты использовали дисциплину для поддержания системы типов, то они бы придумали php. Или js. Все остальные полагаются на инструменты, которые за типизацией следят машинными средствами. Для кода есть объективная возможность его проверять, как спецификации, так и нефункциональным метрикам.
Насчёт "не нужна". Обычно документация нужна новопришедшему в проект. И в этот момент вступительная документация с терминологией и т.д. оказывается адски нерелевантной, но это однократный всплеск, и дальше она опять "не нужна".
Более того, в ревью есть ещё одна драма: человек, который читает ревью, не имеет ни малейшей возможности понять, какие страницы документации это ревью задевает. Код меняют, документацию нет.
Вот в локализации эту проблему решили, кстати. Если вы будете менять строки для l18n софта, то на ревью сразу будет заметно, хорошо с локализацией или нет. И даже роботы придут и пожурят, если что-то пропущено.
RomanBlinov Автор
Дисциплина, в первую очередь, должна обеспечиваться со стороны лидов и РП, если они выстроят процессы, то и банально изменения в интерфейсах и других программных аспектах будут ими отслеживаться с постановкой соответствующих задач писателям и другим заинтересованным лицам. Они же тоже часть команды и их можно привлекать к планированию работ и т.п. митинги, где они опять же смогут фиксировать грядущие изменения и прочие важные моменты.
Что же касается способов следить за изменением кода, то почему не настроить систему так, чтобы она присылала оповещения об изменениях кода и писателям, чтоб они могли своевременно внести изменения в соответствующие блоки документации.
И я опять повторюсь, вопросы актуализации, это в первую очередь, вопросы выстроенных процессов внутри команды, если скинуть необходимость отслеживания изменений на отдельно взятого писателя, который еще и чаще всего не является достаточно компетентным в частных вопросах программирования, ну тогда, скорее всего, да, документация быстро устареет и не будет полезна.
Если же мы применяем соответствующие метрики QA, собираем фидбек и т.п. действия, то актуализация и пополнение документов становятся работой на регулярной основе и позволяют иметь абсолютно достоверную документацию, что уже давно практикуется в различных компаниях с docops - Фолиант в Ростелекоме, xSolla - все живут именно по такой системе, и, вроде бы как, доки у них вполне себе рабочие.
amarao
Дисциплина, которая поддерживается человеками, это очень дорого, очень ненадёжно и очень мало. Дисциплина, которая поддерживается роботами - просто, дёшево, понятно, быстро.
RomanBlinov Автор
Роботы, конечно, хорошо, но как-то странно выглядит команда разработки без иерархии и планирования.
amarao
Я не знаю, зачем вы их принесли в топик. Структура управления в компании может быть любая, я говорю, что если дисциплина в проекте поддерживается людьми, то это сложно, дорого, неудобно и мало. И неконсистентно, чаще всего.
Роботы это делают куда эффективнее.
AlexJameson
Чисто из интереса - у вас есть какой-то готовый кейс или теоретическое решение этой проблемы с вовлечением роботов?
Там где я работаю, робот дополнительно валидирует примеры кода в документации, смотрит актуальность ссылок ну и сообщает об изменениях всяких параметров опций, потому что сама структура параметров генерируется из кода.
Может быть поделитесь вашим планом, что еще можно сделать?
amarao
Нет. Но есть боль, которую надо решать. С технической документацией по интерфейсам и т.д. жить можно, а вот архитектурная гниёт со скоростью рыбы.
Пока (админское) нашёлся plotnetcfg, который может хотя бы сетевую конфигурацию для примеров вынимать из реальных серверов (раньше сетевые диаграммы гнили первыми, потому что редактировать их - то ещё развлечение, да и рисуют их обычно до реализации, так что к концу реализации они уже "не точны").
Но это всё частные случаи. Системно я решения не знаю.
fiddle-de-dee
Что подразумевается под архитектурной документацией? Наверняка её можно поставить как-то в зависимость от артефактов собственно разработки
amarao
архитектурная документация.
Входящий трафик попадает на маршрутизатор, где most-specific маршрут из ibgp утаскивает его через ecmp на сервера балансеров внутри vxlan'ов, а обратно он возвращается штатным маршрутом. Балансеры первого уровня делают ssl и передают на http-only балансировщики второго уровня, которые следят за нагрузкой серверов приложений и балансируют в режиме full-mesh по всем серверам. Каждый балансер второго уровня ведёт свою таблицу liveness и нагрузки.
Фигак, завтра решили, что два слоя жирно, ibgp внутри ручных vxlan'ов - архаика, перешли на evpn с терминацией на хостах силами ovn.
Кто пойдёт и обновит архитектурную документацию? Почему ему надо это сделать? Как он узнает, что это надо сделать? Какой робот его проверит?
fiddle-de-dee
Пропустил сообщение. Я так понимаю, есть схема (картинка), которая призвана кому-то или даже себе помочь разобраться, что и как работает.
Если схема реально работает, значит ее актуальность можно тестировать через
конфиги
логи
журналы учёта событий, в которые вносят замечания люди, например задачи в jir'е с какими-то характеристиками, excel-файлы и что угодно
возможно что-то еще
Общий смысл: схема актуальна, если вот определенные тесты не валятся. Т.е. проверяется не схема, а условия, заложенные при её разработке.
(схему иногда вообще можно сгенерировать автоматически, но тут 50 на 50, либо сможем, либо нет... и иногда хочется высветить важные аспекты схемы... а не всю вермишель)
На первый взгляд сложно, но... (1) если этого нет, то лучше создать документацию в стиле "понажимайте на кнопочки и посмотрите реакцию", без шуток -- просто сориентировать человека или себя в будущем, куда смотреть (2) не так уж и сложно, учитывая современный инструментарий devops и выработанные подходы к тестированию, в частности для упрощения подобного рода задач часто помогает apptovaltesting
amarao
Исключая человеков из процесса тестирования, как проверять схему, например?
fiddle-de-dee
Человек никогда ниоткуда не исключается. Меняется качество (смысл) работы, но меньше её не становится. Может, завтра всё изменится. Посмотрим
Рассмотрим такой пример. Есть схема развертывания легаси легаси информационной системы. Есть bash, который правдами и неправдами считывает различные логи, конфиги и параметры и льет их в текстовый файл с активным использованием sed, простых обработок или вообще без оных.
Полученный файл заливается на git с документацией и при сборке используется простой тест
Если не проходит, сразу видно, что не так, и понятно, что менять.
Если ответственный специалист (например, я) тупо смерджил и залил на гит, понятно, кто виноват.
amarao
Это проверка кода. Как код проверять мы знаем. Как тестировать сайд-эффекты мы знаем.
Как проверить, что на картинке (в тексте architectural overview) если сказано, что "должен лить", то и в коде будет "должен лить"? Обычно документация гниёт таким образом: человек поправил код (потому что есть причины), поправил тесты, а документацию не поправил. И нужен робот, чтобы это поймать. Но как такого робота сконструировать - я пока не понимаю.
Чем меньше в проекте держится на человеках, тем легче такой проект поддерживать в хорошем состоянии.
fiddle-de-dee
Приведенный выше пример проверяет именно документацию. Про сайд-эффекты не понял.
В любом случае такой тест на конфигурацию пишется быстро. Подход проходит даже там, где есть параноидальные требования к закрытости инфраструктуры и ИБ. PR с документацией при изменении конфигурации не пройдёт (от человеческих ошибок и лени мы защищены). Из ошибки теста мгновенно понятно, что изменилось. Куда проще?
amarao
Я реально не понял, как приведённый выше код сообщит, что "на картинке из README.md фигня".
fiddle-de-dee
В комментариях довольно сложно показать.
Скажем, у меня есть схема моей виртуалки, и я должен быть уверен, что в документации она актуальна.
Для этого у нас есть вот такой bash-скрипт.
Он дает на выходе файл
mynote.txtИ файл
flex-params.puДокумент наверху -- это Open Document (LibreOffice), но на самом деле -- это схемка в формате plantuml, обёрнутая Asciidoc'ом (
architect-vision.adoc)Как видим, свободная память сразу засасывается в картинку.
Тестируем всё это, например, через
TestDoc.groovy.Запускаем, например, так:
Если скрипт выдает ошибку, то у нас возникает файл
MyNote.testMyNote.received.txt. Сравниваем его мёрджером сMyNote.testMyNote.approved.txt, который содержит предыдущее состояниеmynote.txt. IDE при запуске теста сразу запускает мёрджер, что удобно.Из рисунка ясно, что памяти стало больше. Корректируем документацию (если нужно -- может, мы округляем память до 10 Гб), мёрджим всё в одобренную версию (approved). Далее собираем документацию, например, так.
И получаем такой же файл, как наверху, только актуальный.
MyNote.testMyNote.approved.txtиmynote.txtнаходятся в системе контроля версий, случайно проигнорировать не получится, только намеренно. Но тут есть другие подходы.amarao
А теперь, предположим, схема поменялась. И реальная схема выглядит так:
(сделайте поправку на то, что я перерисовывал в чём-то своём)
И как это будет отловлено? Не константы, а наличие доп связи.
fiddle-de-dee
В нашем упрощенном случае (если я содержательно правильно понял предложенную ситуацию) можно в баш добавить
Я бы воспринимал это следующим образом.
Документация -- это не конкретная схема или документ, но весь проект (в нашем случае -- код), обеспечивающий актуальность, достоверность и полноту выходных документов.
В этом смысле регресса документации не было. Она была недостаточно хороша, и не дала возможности поймать подключение SSD.
Вот если бы мы подключили ещё SSD или что-то аналогичное и опять бы его прошляпили, это было бы уже регрессом.
Точно так же, как с приложением. Выявили ошибку, заткнули регрессионным тестом.
amarao
Вы предлагаете картинки хранить как граф и тестировать. Для части картинок это работает. А для текста?
fiddle-de-dee
Идея в другом. Есть эксплуатационная документация. Есть её элементы, которые описывают текущее состояния информационной системы. Тут возможны три случая.
Лучший вариант -- автоматическая генерация.
Если автоматическая генерация невозможна, придумываем критерии, которые просигнализируют, что документацию (возможно) надо менять. Оцениваем трудозатраты на такие изменения.
Если критерия нет, или предполагаемые затраты на актуализацию слишком высокие, значит не документируем.