Pull to refresh

Comments 42

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • конфиги

  • логи

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для этого у нас есть вот такой 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 находятся в системе контроля версий, случайно проигнорировать не получится, только намеренно. Но тут есть другие подходы.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

UFO landed and left these words here

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

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

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

UFO landed and left these words here

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

UFO landed and left these words here

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

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

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

Only those users with full accounts are able to leave comments. Log in, please.