Docs as Code – Code as Docs – No Docs

[bkolomin]

Del

[snovikov]

Если интересно, я могу поделиться опытом, как я формирую часть разделов проектной документации на основании XML- файлов, которые описывают ряд аспектов проектируемой информационной системы. Эти же XML- файлы, которые потом могут быть дополнены разработчиком, включаются в сборку прикладного кода.
Таким образом у меня исходный код (в виде XML-файлов) у меня является источником для формирования документации. Я использую такой подход как при проектировании новых сущностей в системе, так и при восстановлении документации к уже реализованным сущностям.
Да, есть ограничения платформы, с помощью которой создаются прикладные решения.
Для разработки мы (ну и получается для документирования некоторых аспектов информационной системы) мы используем инструментальную среду разработки, которую создали самостоятельно (можно сказать что это no code-система).

[snovikov]

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

[chemaxm]

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

Далее генерация ASCIIDOC и plantuml.

Хочу допилить до генерации helm или Ansible плэйбуков (из перезаполненных ролей) но руки никак не доходят.

А что описываете в XML?

[chemaxm]

У меня не получилось запихнуть всю нужную информацию в один читаемый\нормально рендерещийся plantUML (конечно слабый аргумент, то что не получилось, не значит что нельзя). Достаточным описанием для меня одно время был DSL Structurizr, кроме того удобна встроенная генерация небольших схем-взглядов из единого описания, но субъективно у меня с ним не сложились отношения. Возможно упомянутый MOF (или расширенный UML на нем) - был бы решением, но никогда в него глубоко не погружался, возможно стоит.

Посмотрел упомянутую Finitomata она как раз генерирует из стандартного PlantUML\Mermaid. Надо попробовать, давно хотел пощупать Elixir, будет хороший повод.

[DMS_13]

Сейчас все работают именно по схеме фиксации кода.

Эмм... нет, это компании с незрелыми процессами разработки так работают.

Компании со зрелыми процессами давно работают с documentation first. А те кто хотят это делать быстро и эффективно реализуют его через doc as code.

[chemaxm]

В такой формулировке согласен.

Видимо неточно сформулировал мысль. Подумаю как поправить, чтобы правильно быть понятым. Вероятно позаимствую часть вашей формулировки

[DMS_13]

Вы никогда не думали, что делая подробное ТЗ вы делаете двойную работу? Вначале аналитик подробно описывает все алгоритмы и спецификации, а потом разработчик делает то же самое, но на другом языке.

Это некорректно сравнение. Разработчик производит код. Это результат.

Документация описывает этот код.

Вы же не будете утверждать, что план разводки розеток и сами провода, лежащие в стене, это одно и тоже???

[chemaxm]

В этой и есть то что хотелось обсудить

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

Но с кодом есть сам код, который условно "на виду" и читаем.

[Cordekk]

С текущим развитием ИИ и лоу-код систем уже больше приходится говорить о другой схеме
Docs as Code –> Code from Docs – No Code

[heejew]

-> No Code and No Docs