17.09.2021 11:55
RomanBlinov 42 3600 Источник

Привет, Хабр! Меня зовут Роман Блинов, я ведущий технический писатель в «Цифре» — в команде по развитию платформы 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)


  1. amarao
    17.09.2021 12:26
    #23493290
    +1

    Во всём этом я вижу два тезиса:

    • Документация в гите

    • Ревью документации.

    Это работает, но только для операционных вопросов. От сгнивания документации это не спасает. От соответствия документации и кода это не спасает. Причина? Когда код ломается, мы это видим. Когда документация сгнивает (перестаёт быть актуальной или даже противоречит происходящему) мы это замечаем потом. Когда нибудь.

    А вот как увидеть, что документация сгнила? Ручное тестирование документации? Это ещё хуже, чем ручное тестирование продукта. Где наш AI, который может вычитывать документацию и говорить, что содержимое не соответствует происходящему в окружающем мире?


    1. RomanBlinov Автор
      17.09.2021 12:38
      #23493336

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

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

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

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


      1. amarao
        17.09.2021 12:51
        #23493372

        Если бы программисты использовали дисциплину для поддержания системы типов, то они бы придумали php. Или js. Все остальные полагаются на инструменты, которые за типизацией следят машинными средствами. Для кода есть объективная возможность его проверять, как спецификации, так и нефункциональным метрикам.

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

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

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


        1. RomanBlinov Автор
          17.09.2021 13:06
          #23493424

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

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

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

          Если же мы применяем соответствующие метрики QA, собираем фидбек и т.п. действия, то актуализация и пополнение документов становятся работой на регулярной основе и позволяют иметь абсолютно достоверную документацию, что уже давно практикуется в различных компаниях с docops - Фолиант в Ростелекоме, xSolla - все живут именно по такой системе, и, вроде бы как, доки у них вполне себе рабочие.


          1. amarao
            17.09.2021 15:12
            #23493976
            +1

            Дисциплина, которая поддерживается человеками, это очень дорого, очень ненадёжно и очень мало. Дисциплина, которая поддерживается роботами - просто, дёшево, понятно, быстро.


            1. RomanBlinov Автор
              17.09.2021 15:14
              #23493990

              Роботы, конечно, хорошо, но как-то странно выглядит команда разработки без иерархии и планирования.


              1. amarao
                17.09.2021 15:17
                #23494002

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

                Роботы это делают куда эффективнее.


                1. AlexJameson
                  19.09.2021 11:38
                  #23498362
                  +1

                  Чисто из интереса - у вас есть какой-то готовый кейс или теоретическое решение этой проблемы с вовлечением роботов?

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

                  Может быть поделитесь вашим планом, что еще можно сделать?


                  1. amarao
                    19.09.2021 12:38
                    #23498506
                    +1

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

                    Пока (админское) нашёлся plotnetcfg, который может хотя бы сетевую конфигурацию для примеров вынимать из реальных серверов (раньше сетевые диаграммы гнили первыми, потому что редактировать их - то ещё развлечение, да и рисуют их обычно до реализации, так что к концу реализации они уже "не точны").

                    Но это всё частные случаи. Системно я решения не знаю.


                    1. fiddle-de-dee
                      22.09.2021 22:52
                      #23511544

                      Что подразумевается под архитектурной документацией? Наверняка её можно поставить как-то в зависимость от артефактов собственно разработки


                      1. amarao
                        23.09.2021 14:53
                        #23513408

                        архитектурная документация.

                        Входящий трафик попадает на маршрутизатор, где most-specific маршрут из ibgp утаскивает его через ecmp на сервера балансеров внутри vxlan'ов, а обратно он возвращается штатным маршрутом. Балансеры первого уровня делают ssl и передают на http-only балансировщики второго уровня, которые следят за нагрузкой серверов приложений и балансируют в режиме full-mesh по всем серверам. Каждый балансер второго уровня ведёт свою таблицу liveness и нагрузки.

                        Фигак, завтра решили, что два слоя жирно, ibgp внутри ручных vxlan'ов - архаика, перешли на evpn с терминацией на хостах силами ovn.

                        Кто пойдёт и обновит архитектурную документацию? Почему ему надо это сделать? Как он узнает, что это надо сделать? Какой робот его проверит?


                      1. fiddle-de-dee
                        05.10.2021 09:46
                        #23555306

                        Пропустил сообщение. Я так понимаю, есть схема (картинка), которая призвана кому-то или даже себе помочь разобраться, что и как работает.

                        Если схема реально работает, значит ее актуальность можно тестировать через

                        • конфиги

                        • логи

                        • журналы учёта событий, в которые вносят замечания люди, например задачи в jir'е с какими-то характеристиками, excel-файлы и что угодно

                        • возможно что-то еще

                        Общий смысл: схема актуальна, если вот определенные тесты не валятся. Т.е. проверяется не схема, а условия, заложенные при её разработке.

                        (схему иногда вообще можно сгенерировать автоматически, но тут 50 на 50, либо сможем, либо нет... и иногда хочется высветить важные аспекты схемы... а не всю вермишель)

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


                      1. amarao
                        05.10.2021 09:56
                        #23555334

                        Исключая человеков из процесса тестирования, как проверять схему, например?


                      1. fiddle-de-dee
                        06.10.2021 22:46
                        #23562112
                        +1

                        Человек никогда ниоткуда не исключается. Меняется качество (смысл) работы, но меньше её не становится. Может, завтра всё изменится. Посмотрим

                        Рассмотрим такой пример. Есть схема развертывания легаси легаси информационной системы. Есть bash, который правдами и неправдами считывает различные логи, конфиги и параметры и льет их в текстовый файл с активным использованием sed, простых обработок или вообще без оных.

                        Полученный файл заливается на git с документацией и при сборке используется простой тест

                            import org.approvaltests.Approvals
    ...
    @Test
    void checkMyGreatPainting() throws IOException {
        String content = Files.readString(Path.of("путь к файлу с полученной солянкой"), StandardCharsets.UTF_8);
        Approvals.verify(content);
    }
    ...

                        Если не проходит, сразу видно, что не так, и понятно, что менять.

                        Если ответственный специалист (например, я) тупо смерджил и залил на гит, понятно, кто виноват.


                      1. amarao
                        07.10.2021 11:46
                        #23563628

                        Это проверка кода. Как код проверять мы знаем. Как тестировать сайд-эффекты мы знаем.

                        Как проверить, что на картинке (в тексте architectural overview) если сказано, что "должен лить", то и в коде будет "должен лить"? Обычно документация гниёт таким образом: человек поправил код (потому что есть причины), поправил тесты, а документацию не поправил. И нужен робот, чтобы это поймать. Но как такого робота сконструировать - я пока не понимаю.

                        Чем меньше в проекте держится на человеках, тем легче такой проект поддерживать в хорошем состоянии.


                      1. fiddle-de-dee
                        09.10.2021 12:12
                        #23571824

                        Приведенный выше пример проверяет именно документацию. Про сайд-эффекты не понял.

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


                      1. amarao
                        09.10.2021 13:43
                        #23572128

                        Я реально не понял, как приведённый выше код сообщит, что "на картинке из README.md фигня".


                      1. fiddle-de-dee
                        12.10.2021 20:03
                        #23584466
                        +1

                        В комментариях довольно сложно показать.

                        Скажем, у меня есть схема моей виртуалки, и я должен быть уверен, что в документации она актуальна.

                        Для этого у нас есть вот такой bash-скрипт.

                        echo "My note" >mynote.txt
grep MemTotal /proc/meminfo >> mynote.txt
df -t ext4 --output=size >> mynote.txt
df -t ext4 --output=avail -B G | grep "[0-9]\+G$" | sed 's/ //g' \
  | sed -e 's/\([0-9]\+G\)/!$available_hdd = "\1b"/g' > flex-params.pu

                        Он дает на выходе файл mynote.txt

                        My note
MemTotal:       10816304 kB
1K-blocks
 65274444

                        И файл flex-params.pu

                        !$available_hdd = "16G"

                        Документ наверху -- это Open Document (LibreOffice), но на самом деле -- это схемка в формате plantuml, обёрнутая Asciidoc'ом (architect-vision.adoc)

                        = My note configuration

== HDD and Memory

[plantuml, png, fitrect="210x260mm", srcdpi="300", width="40%"]
.My notebook configuration
....
skinparam dpi 300
include::flex-params.pu[]
package "My note" {
    component hdd [
      HDD
      ----
      Total: 64Gb
      Available: $available_hdd
    ]
    component memory [
      Memory
      ----
      10Gb
    ]
memory -- hdd
....

                        Как видим, свободная память сразу засасывается в картинку.

                        Тестируем всё это, например, через TestDoc.groovy.

                        @Grapes([
    @Grab(group='com.approvaltests', module='approvaltests', version='12.1.1')
])
import org.junit.jupiter.api.Test
import org.approvaltests.Approvals
import java.nio.charset.StandardCharsets
import java.nio.file.Files
import java.nio.file.Path
class MyNote {
    @Test
    void testMyNote() {
        String content = Files.readString(Path.of("mynote.txt"), StandardCharsets.UTF_8);
        Approvals.verify(content);
    }
}

                        Запускаем, например, так:

                        docker run --rm -u root -v "$PWD":/home/groovy/scripts -w /home/groovy/scripts groovy groovy TestDoc.groovy

                        Если скрипт выдает ошибку, то у нас возникает файл MyNote.testMyNote.received.txt. Сравниваем его мёрджером с MyNote.testMyNote.approved.txt, который содержит предыдущее состояние mynote.txt. IDE при запуске теста сразу запускает мёрджер, что удобно.

                        Сравнение конфигураций
                        Сравнение конфигураций

                        Из рисунка ясно, что памяти стало больше. Корректируем документацию (если нужно -- может, мы округляем память до 10 Гб), мёрджим всё в одобренную версию (approved). Далее собираем документацию, например, так.

                        docker run --rm -v $(pwd):/documents/ curs/asciidoctor-od a-od architect-vision.adoc odt

                        И получаем такой же файл, как наверху, только актуальный. MyNote.testMyNote.approved.txt и mynote.txt находятся в системе контроля версий, случайно проигнорировать не получится, только намеренно. Но тут есть другие подходы.


                      1. amarao
                        13.10.2021 13:43
                        #23586764

                        А теперь, предположим, схема поменялась. И реальная схема выглядит так:

                        (сделайте поправку на то, что я перерисовывал в чём-то своём)
                        И как это будет отловлено? Не константы, а наличие доп связи.


                      1. fiddle-de-dee
                        13.10.2021 16:14
                        #23587526

                        В нашем упрощенном случае (если я содержательно правильно понял предложенную ситуацию) можно в баш добавить

                        df --output=source,target | grep убрать что-то сиюсекундное >>  mynote.txt

                        Я бы воспринимал это следующим образом.

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

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

                        Вот если бы мы подключили ещё SSD или что-то аналогичное и опять бы его прошляпили, это было бы уже регрессом.

                        Точно так же, как с приложением. Выявили ошибку, заткнули регрессионным тестом.


                      1. amarao
                        13.10.2021 21:15
                        #23588568

                        Вы предлагаете картинки хранить как граф и тестировать. Для части картинок это работает. А для текста?


                      1. fiddle-de-dee
                        17.10.2021 22:35
                        #23600098

                        Идея в другом. Есть эксплуатационная документация. Есть её элементы, которые описывают текущее состояния информационной системы. Тут возможны три случая.

                        Лучший вариант -- автоматическая генерация.

                        Если автоматическая генерация невозможна, придумываем критерии, которые просигнализируют, что документацию (возможно) надо менять. Оцениваем трудозатраты на такие изменения.

                        Если критерия нет, или предполагаемые затраты на актуализацию слишком высокие, значит не документируем.


  1. ophil
    17.09.2021 14:21
    #23493742

    Странно, в статье ни разу не встретилось слово гитхаб. Всё перечисленное там уже есть, плюс gitpages, wiki, issues, discussions, gists. И тысячи проектов с примерами вполне актуальной документации и налаженной работы команд.


    1. RomanBlinov Автор
      17.09.2021 14:38
      #23493826

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


  1. Mur466
    18.09.2021 03:01
    #23495582
    +1

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

    Концентрация на улучшении процесса написания, а не использования документации.

    Если цель ведения документации — спихнуть что-то заказчику, чтобы формально закрыть договор, то подход имеет право на жизнь.

    Если документация пишется, чтобы ею пользовались, то главным критерием улучшений должно быть удобство использования и качество содержания. Отсюда вытекает confluence или другая продвинутая wiki с мощным поиском, плагинами для диаграмм и прочими плюшками, кстати версионирование страниц там есть и без гита. А также необходимо регулярное чтение документации не только самим писателем или разработчиком темы, но и аналитиком или другим человеком "со стороны", который вдумчиво будет пытаться сопоставить набор слов с тем, что они в реальности описывают, задавать вопросы и требовать уточнений.

    Наверное merge request имеет право на жизнь, но это только если трудится целая группа писателей.

    Программисты должны непременно быть вовлечены, но гит использовать для этого вовсе не обязательно.

    Главная проблема технической документации — ее бесполезность в силу формального подхода к написанию и быстрого "протухания". Указанный в статье подход никак с этими проблемами не борется. Похоже на карго-культ методик и инструментов разработки.


    1. RomanBlinov Автор
      18.09.2021 19:46
      #23497138

      Добрый вечер. Подход docops никогда не ставил целью спихивать что-либо заказчикам или как-то концентрироваться на качестве отдельных документов. Плохой документ может создаваться и ворде, и в конфлюенс и в гите. Суть данного подхода в автоматизации тех практик, которые сейчас практически полностью ручные: 1. Формат документа - простая читаемая разметка; 2. Использование для написания техник аналогичных техникам разработки, 3. Отсутствие необходимости актуализации доков в 100 источниках (конфлюенс хорош, когда он один, а что делать если аналогичная документация развернута у заказчиков, и каждый из них просит тот формат, что ему удобен? На каждом ресурсе каждый из нескольких десятков доков обновлять? Как-то минимально продуктивно), единый процесс доставки, когда заказчик получает новую версию документа с новой версией сервиса, и т.п. В этом суть docs as code.


    1. XVlady5
      18.09.2021 19:47
      #23497142

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

      Для себя нашёл один выход - писать в md, в ci лить в конфлю, обсуждать в ней же, результат фиксить в md/git/реквест на слияние.

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


      1. RomanBlinov Автор
        18.09.2021 19:51
        #23497150

        Интересная мысль, но честно говоря, не очень себе представляю, как поженить md и конфлюенс? Или там все-таки отображается только ссылка?


        1. XVlady5
          20.09.2021 19:32
          #23502958

          У confluence неплохой api. А нашего экземпляра нет возможности хранить md, поэтому ci дополняется cd, генерящий html из md с рядом правок под извращения confluence и обновляет страницы


          1. RomanBlinov Автор
            20.09.2021 21:38
            #23503398

            Спасибо. Интересно, надо слазить внутрь конфы. Честно говоря, как-то не задавался такими способами.


  1. kRosis
    19.09.2021 21:28
    #23499630
    +1

    А что, собственно, мешает переместить бегущего позади писателя на остриё разработки?

    Поясню, из личного опыта. Вот обсуждаем с командой новый функционал, вместе с нами сидит писатель и записывает обсуждение. Если у него возникают какие-то вопросы - он может их задать. Далее пишется документация, параллельно создаются эпики, таски и т.д. И разработчики создают тот функционал, который описан в wiki, не больше не меньше. Фактически краткое описание фич в задачах, развёрнутое в wiki и если возникают нестыковки, то люди обращаются к wiki, а потом смотрят в код. Оговорюсь, что наш писатель находится в контексте продукта.

    Таким образом в wiki всегда актуальная и наиболее полная информация.

    Для вики полно хороших инструментов confluence, gitlab wiki, etc. Которые имею page history. В readme.md описывается узкая информация по конкретному приложению.


    1. RomanBlinov Автор
      19.09.2021 21:37
      #23499660

      Добрый вечер! На самом деле ничто не мешает. просто Ваша модель документирования опирается на другой инструмент и больше соответствует docs as service - это так же рабочая модель, и так же применяется. Просто если у Вас в процессе какого-либо этапа разработки возникнет изменение или дополнение, то пока вы не посадите техписа рядом, он не узнает об этом, а когда до него дойдет постановка, пока он разберется, пока напишет и донесет до команды. Такая модель хорошо работает, когда у вас идеально отработан процесс постановки задач писателям, а если нет? А как быть, когда ваш продукт развивается на глазах и когда новые фичи становятся базовыми сервисами в течение одного-двух дней, ждать митинга с писателем? Docs as code работает, и когда команда не успела ему сообщить, банальные уведомления приходят.


      1. kRosis
        19.09.2021 23:15
        #23499914
        +1

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

        Пилили стартап в таком стиле, вроде никаких проблем замечено не было.

        Такая модель хорошо работает, когда у вас идеально отработан процесс постановки задач писателям, а если нет?

        Не очень понимаю словосочетания "процесс постановки задач писателям", какие задачи им требуется ставить?

        Наш подход работает хорошо отчасти потому что на 1 команду 1 писатель. Как организовать работу одному писателю для 2 и более команд - вопрос хороший. Из предположений - проводить митинги не в одно время, чтоб писатель мог присутствовать на всех.


        1. RomanBlinov Автор
          20.09.2021 08:36
          #23500488

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

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

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


  1. gmtd
    20.09.2021 10:03
    #23500696
    +1

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

    Javadoc (странно, что он ни разу не упомянут) является в данном случае для меня идеалом данного подхода, и за 25 лет использования доказал свою практичность.

    Однако проблема в средствах генерации для других систем.

    Взять популярные фреймворки - Vue.js например. Есть отдельные индивидуальные попытки создать jsdoc и прочее, но хорошего качественного средства так почему-то никто и не сделал. А жаль. Это очень нужная штука даже для команды из одного-двух программеров, не говоря уж больших группах разработчиков.


    1. AZaz1
      21.09.2021 21:04
      #23507860
      +2

      все попытки использовать jsdocs и подобные с треском провалились из-за долгих танцев с бубном по форматированию всего этого описания и необходимости помнить сущности связанные с форматированием этих описаний

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

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


  1. ivanych
    27.09.2021 09:42
    #23524670

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

    Удобно - это Конфлюенс, всегда доступный, с поиском, оглавлением и прочими плюшками.

    Вы мельком упомянули некий pandoc - что это? Какой- то инструмент для извлечения документации из кода и помещения извлечённой документации в Конфлюенс? Вы именно так делаете? В CI автоматически запускается экспорт в Конфлюенс?

    Если экспорт в Конфлюенс не происходит - как предлагается читать документацию?


    1. RomanBlinov Автор
      27.09.2021 11:38
      #23525166

      Добрый день! Подробное рассмотрение вопроса публикации документации в данном подходе просто не вошло в статью ввиду значительного объема материала. Если вкратце, то подход docs as code предполагает, что документация готовится для размещения онлайн, и у нас имеется соответствующий инструмент, который собирает материалы в ветках гита и публикует их, после чего материалы доступны заказчику и другим заинтересованным лицам. С самого ресурса документация может быть скачана в необходимом формате, для этого как-раз и используется утилита Pandoc, которая конвертирует документы в те форматы, которые необходимы и обладает достаточно широкими способностями для настройки, например, позволяет применить для оформления документа корпоративный шаблон.

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

      Что же касается вопроса использования конфлюенс - тут есть базовые проблемя для размещения документации, которые никто не решил: 1. Доступ к документам (размещать у себя и давать доступ для заказчика? Не очень разумный вариант, т.к. в этом случае вы пустите в свою базу знаний сторонних лиц, которым там, может быть, и незачем находиться); 2. Размещение документов на ресурсах заказчика ( а если заказчик не пользуется конфлюенс? Экспорт из него ну вот никак нельзя назвать нормальным - это весьма проблемный документ, который требует очень глубокой проверки и доработки, т.к. из него часто банально пропадают изображения и схемы, а кроме этого такой документ невозможно оформить в соответствии с требованиями заказчика, например, в его корпоративном шаблоне. Также, заказчик вполне может применять в своей работе какую-нибудь иную вики-базу, x-wiki например, которая тоже весьма проблематично взаимодействует с конфлюенсом. А наш подход позволяет создать документ в таком формате и разметке, который является универсальным и легко может быть подготовлен для импорта в системы заказчика, либо просто может быть передан через CI.


      1. ivanych
        27.09.2021 19:45
        #23527038

        Простите, но без рассмотрения вопроса чтения вопрос написания становится бессмысленным. Вот написал я документацию в коде - иии? Как читать-то?

        Вы какой-то обтекаемый ответ даёте - "ну как там надо будет заказчику в таком формате и будет".

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


        1. RomanBlinov Автор
          28.09.2021 07:21
          #23528234

          У нас она собирается на соответствующем ресурсе в сети, к которому настраивается доступ, и где ее можно в любой момент посмотреть и получить. Наши документы в открытом доступе не лежат, но в качестве примера можно привести такую страничку - https://developers.xsolla.com/subscriptions-api/. Принцип аналогичный.


          1. ivanych
            28.09.2021 09:20
            #23528446

            Абажжите... по ссылке находится спецификация API и это совсем не то же самое, что документация. Спека - это один простой текстовый файл, плюс скрипт на яваскрипте, который его рендерит. Там и извлечения-то документации никакого вообще нет - спека просто доступна по урлу как отдельный ендпойт API.

            Вы всё это время говорили о спеках API что ли?

            Я-то подразумевал развесистую многостраничную документацию. Ну, вот как в Конфлюенсе - разделы, страницы, ссылки между страницами. Такое у вас делается? Какими средствами? Где, если не в Конфлюенсе, такую документацию читать?


            1. RomanBlinov Автор
              28.09.2021 10:07
              #23528620

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

              Если перейдете на другие страницы ссылки, там будут и другие документы. И все они многостраничные с перекрестными ссылками, рисунками, схемами и т.п.

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