Pull to refresh
28
Karma
8
Rating
Поташников Николай Михайлович @fiddle-de-dee

Системный аналитик

  • Followers 17
  • Following 3

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

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

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

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

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

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

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

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

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

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

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

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

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

Автоматизированная сборка документа «Текст программы» по ЕСПД с помощью python-docx

Прямая генерация docx-файлов из кода имеет потолок. Более простым выглядит использование MD (например, через Фолиант), rst, Asciidoc, да даже Docbook или DITA. Общая цепочка сложнее, но сама генерация в разы проще. Для объединения текстовых файлов с исходниками это не так важно. Но завтра в документ необходимо будет внести дополнительные сведения. Послезавтра сделать подсветку синтаксиса и т.д. Всё можно запрограммировать, но мы же за эффективность.

И, конечно, очень интересно при всех попытках борьбы с проприетарным ПО соседство слов ГОСТ и docx. Да даже если забыть о борьбе с проприетарным ПО. Та же операция обновления полей и получения pdf -- нужен MS Word. А он платный. И под linux не работает. Прощай непрерывная интеграция. На самом деле, прощай документация. Получается, документ мы делаем для галочки, чтобы сдать, а не чтобы им пользовались. Он устаревает, не успев появиться

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

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

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

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

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

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

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

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

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

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

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

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

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

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

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

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

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

  • конфиги

  • логи

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

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

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

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

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

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

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

Как закалялась документация

Справедливости ради, Asciidoctor поддерживает, как минимум, 5 pdf-ориентированных технологий. Для разных случаев от генерации ГОСТовской документации до создании дизайнерских листовок. Поэтому экстравагантные решения типа HTML->PDF, возможно, излишни. Хотя... всякое бывает

Подскажите, пожалуйста, чем пользовались для публикации в Confluence?

Автоматическая генерация технической документации

Спасибо, очень хороший пример. Чтобы упросить чтение читателям вашего комментария, сразу приведу картинку (использовал kroki). Также держим в уме, что самостоятельно сделать шаблон для генерации аналогичной картинки (например, если есть специфические требования к отображению в конкретном документе) — это несколько десятков строчек достаточно простого кода.
image

Автоматическая генерация технической документации

Спасибо за отзыв. По поводу «ворд». Мне кажется — это правильный формат для стейкхолдеров. Word удобен для использования текста, для печати, для ревизии. Например, при написании статей для хабр я отработал следующий механизм. Пишу в Asciidoc, компилирую в Word или Open Document и отсылаю на ревизию. Далее компилирую в habr md-формат и публикую. Единственная ручная операция — копипаст получившегося md-файла.


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

Автоматическая генерация технической документации

  1. Да, действительно, документации можно сгенерировать много, а можно по делу… При этом необходимо понимать, что мы, как правило, генерируем не документацию, а куски, которые инкапсулируем в общий проект документации. В этом и сила Asciidoc и аналогичных инструментов
  2. По поводу борьбы с косяками будет следующая статья
  3. См. первый пункт. Автоматическая генерация — это возможность, которую в некоторых случаях целесообразно использовать, не более того

Asciidoc для ЕСКД

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


Например, требование: "я хочу покрасить ячейку в красный цвет", — необходимо переформулировать примерно так: "я хочу атрибут, который определяет резко негативное отношение к данным в ячейке". Красной ячейка будет или нет (или красным будет только текст) решает специалист, разрабатывающий форматирование.


Форматирование берёт на себя backend. Более того, оно вариативно. Например, ГОСТ ЕСКД разрешает нумеровать графический материал внутри раздела или в разделах допускает сквозную нумерацию. Титул вообще очень вариативен. Ну и всякие рамочки, колонтитулы и т.д.


Поэтому я заложил в бэкенд большую степень кастомизируемости: на уровне шаблона, на уровне препроцессинга содержания, на уровне программного переопределения стилей Open Document. Но, в целом, это не очень сложно. Например, данную статью я писал в Asciidoc а для рецензирования отправлял в docx. Кастомизация стилей с нуля заняла не более получаса. Мне кажется (как человеку писавшему этот текст), что здесь написано достаточно, чтобы понять основные принципы https://courseorchestra.github.io/asciidoctor-open-document/. Если что-то описано недостаточно, криво или есть конкретные юзкейсы пишите Issue или в личку.

Asciidoc для ЕСКД

Именно такая беда и побудила создать backend)) Pandoc вообще не подошёл, мы прогоняли через html

Asciidoc для ЕСКД

footnote — ключевое слово Asciidoc, поэтому тут без вариантов.


Касательно транслита, специально в тексте статьи указал, что мы используем доработанный ГОСТ 7.79-2000 (система Б). Причины доработки здесь: https://github.com/CourseOrchestra/course-doc/blob/master/doc/gost-translit.adoc


Если мы автоматизируем процессы, связанные с применением российского законодательства, то использование транслита оправдано. Термины, раскрытые в нормативном акте, крайне сложно хорошо переводить на английский. То же "Место составления (издания)" вы перевели как "Place of issue". Хотя основное слово здесь — "составление", а не издание (выпуск), которое не имеет хорошего перевода, отражающего его смысл.


Я не говорю о поиске хорошего перевода для специфических терминов, например "Контрольно-надзорное мероприятие" и "Контрольно-надзорное действие".

Asciidoc для ЕСКД

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

AsciiDoc как стандарт для подготовки документации

Интересно то, что второй пункт — свойственен всем системам подготовки документации (как основанным на XML, так и основанным на текстовой разметке). Также по этому пункту все эти системы проигрываются тому же Word'у. Действительно, куда как проще вносить изменения в конечный документ. Ну и этот пункт наиболее непонятный в реализации, хотя выглядит как реализуемый при должном продумывании

AsciiDoc как стандарт для подготовки документации

Да, тут без вариантов)

AsciiDoc как стандарт для подготовки документации

Почему сопутствующей? Что мешает основной?

Бюрократизация IT

К СПДС отношение гораздо лучше, чем к программной документации. Она лучше формализована (здание в отличие от программы можно потрогать). Проблема именно с программной документацией (не важно, ГОСТ 19, ГОСТ 34) заключается в том, чтобы она сохраняла актуальность на всём этапе жизненного цикла программного продукта. Очень многие заказчики этого не понимают, а разработчики в этом просто не заинтересованы.

Information

Rating
537-th
Location
Москва, Москва и Московская обл., Россия
Registered
Activity