Хабр Курсы для всех
РЕКЛАМА
Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!
Хабр доступен 24/7 благодаря поддержке друзей
Комментарии 17
Гениальные идеи не сто́ят даже бумаги, на которой они изложены. Покажите имплементацию, реальный код, который всё это делает, иначе это всё — мусор, отрыжка неокрепшего мозга.
Del
Если интересно, я могу поделиться опытом, как я формирую часть разделов проектной документации на основании XML- файлов, которые описывают ряд аспектов проектируемой информационной системы. Эти же XML- файлы, которые потом могут быть дополнены разработчиком, включаются в сборку прикладного кода.
Таким образом у меня исходный код (в виде XML-файлов) у меня является источником для формирования документации. Я использую такой подход как при проектировании новых сущностей в системе, так и при восстановлении документации к уже реализованным сущностям.
Да, есть ограничения платформы, с помощью которой создаются прикладные решения.
Для разработки мы (ну и получается для документирования некоторых аспектов информационной системы) мы используем инструментальную среду разработки, которую создали самостоятельно (можно сказать что это no code-система).
Код реализации — заинтересовал бы, а опыт — этого говна у самих в достатке.
Я 23 года тому назад в Берлине участвовал в разработке nocode, где в качестве источника правды использовались MOF- (мета-UML) диаграммы. Для генерации кода туда-обратно мы использовали хаскель, и оно даже как-то худо-бедно летало (потом деньги инвесторов иссякли, мне надоело в Германии, и я не знаю, закончилось ли оно чем-нибудь в итоге).
Еще я — автор библиотеки, которая в качестве описания конечных автоматов использует стейт-диаграммы PlantUML/Mermaid. На основе описания создаётся документация, инвалидируется сам конечный автомат и генерируется весь код, кроме собственно хендлеров переходов. Исходники открыты, если что. Я не закапываю инструменты общего назначения за корпоративный файрвол.
мой код вряд ли кому-то будет интересен, так как это банальный парсинг XML-файлов и генерация статьи в конфлюэнсе по шаблону. Тем более, что структура этих XML-файлов специфичная и используется только при создании прикладных решений на платформенном ПО, автором которого мы и являемся (мы- компания где я работаю).
Пошел по тому же пути, только формирую YAMLы как более читаемы. Описываю в них диаграммы развертывания и компоненты.
Далее генерация ASCIIDOC и plantuml.
Хочу допилить до генерации helm или Ansible плэйбуков (из перезаполненных ролей) но руки никак не доходят.
А что описываете в XML?
формирую YAMLы
Из чего формируете? Руками? Тогда гораздо разумнее руками создавать диаграммы UML.
У меня не получилось запихнуть всю нужную информацию в один читаемый\нормально рендерещийся plantUML (конечно слабый аргумент, то что не получилось, не значит что нельзя). Достаточным описанием для меня одно время был DSL Structurizr, кроме того удобна встроенная генерация небольших схем-взглядов из единого описания, но субъективно у меня с ним не сложились отношения. Возможно упомянутый MOF (или расширенный UML на нем) - был бы решением, но никогда в него глубоко не погружался, возможно стоит.
Посмотрел упомянутую Finitomata она как раз генерирует из стандартного PlantUML\Mermaid. Надо попробовать, давно хотел пощупать Elixir, будет хороший повод.
запихнуть всю нужную информацию в один читаемый\нормально рендерещийся plantUML
Эммм… А зачем, точнее — нахрена? Чем несколько плохи?
упомянутый MOF (или расширенный UML на нем)
MOF нужен не чтобы расширять UML (его не расширить: он описывает буквально всё во вселенной, если что). MOF нужен, чтобы строить нишевые UML-подобные языки, краткие, ёмкие и внятные, под вашу доменную область. Такой себе DSL.
давно хотел пощупать Elixir, будет хороший повод
Пощупать — я бы взял что-нибудь попроще (не в смысле «вы не поймете», конечно, просто finitomata слишком много закапывает под капот, а сам код — в результате довольно запутан и построен целиком на макросах, за которые лучше браться не на стадии знакомства), но дело ваше, буду только рад.
Сейчас все работают именно по схеме фиксации кода.
Эмм... нет, это компании с незрелыми процессами разработки так работают.
Компании со зрелыми процессами давно работают с documentation first. А те кто хотят это делать быстро и эффективно реализуют его через doc as code.
Вы никогда не думали, что делая подробное ТЗ вы делаете двойную работу? Вначале аналитик подробно описывает все алгоритмы и спецификации, а потом разработчик делает то же самое, но на другом языке.
Это некорректно сравнение. Разработчик производит код. Это результат.
Документация описывает этот код.
Вы же не будете утверждать, что план разводки розеток и сами провода, лежащие в стене, это одно и тоже???
С текущим развитием ИИ и лоу-код систем уже больше приходится говорить о другой схеме
Docs as Code –> Code from Docs – No Code
-> No Code and No Docs
No, code, no docs
No, code, no docs
No, code, no docs
No, code, no docs‘Cause, ‘cause, ‘cause I remember when we used to write
Code right in the emacs or vim
Oba, observing the hypocrites, yeah
Who used Visual Studio crap, yeah
Good friends we have had, oh, good friends we’ve lost along the way, yeah
In this great future you can’t forget your past
So stop writing code I say, yeah
Write docs. — Bob Marley
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Docs as Code – Code as Docs – No Docs