в смысле википодобных документационных маркапов, в tex с ними все хорошо)

Понятно)

По поводу plantuml... Я так понял, что это средство для рисования блок-схемы или каких-то юмл активити диаграмм при помощи т.н. описательного алготритмического языка, да?
То есть... если сделать парсер, который переводит, скажем, pl/sql код в такого рода язык, то по нему потом можно генерить диаграммы, да? Тут вроде мелькали такие мысли)

Да, javadoc, конечно, подходит. Но javadoc мы не используем, потому что с нас заказчики, как правило, не требуют документацию на код.

Вот здесь мы реализовали утилитку, которая как раз по миграционному скрипту генерирует схемы plantuml и текстовое описание https://github.com/CourseOrchestra/2bass. Но мы используем идемпотентный подход к миграциям. Многие его боятся

Все верно, но (strong opinion) документация на ПО должна генерироваться по коду, а не по рабочей (или тестовой копии) базы данных. Иначе синхронизировать версии ПО и документации будет просто невозможно. По рабочей копии можно генерировать какие-то отчеты о функционировании.. "сегодня было так-то, вот вам табличка и графичек".

Все-таки, еще раз акцентирую вопрос с таблицам. Возможно, я не прав, буду рад разубедиться, но таблицы — самая большая дыра вики-разметок. В markdown colspan и rowspan не поддерживаются, списки внутри таблицы тоже. Задание ширин колонок — тоже. Таблицы с длинным текстом крайне сложно редактировать.  Все, конечно, можно сделать через прямой html, но это же не markdown. В rst тоже сложные таблицы, как они сами пишут 'cumbersome to create'. Asciidoc, по-моему, наиболее хорош в части таблиц, но.. стили ячеек задавать нельзя, строка заголовков может быть только одна.

Ну... дело в том, что у нас нет исходного кода всея БД) Так бывает))
Все апдейты, конечно, через скрипты, но это апдейты.
Да в общем не проблема сделать нормальный реверс инжиниринг и получить код БД.
А потом, да, любые апдейты снабжать комментариями...
Просто у нас, кроме самих таблиц в БД, есть ещё логика на pl/sql, вот там уже код в документации это отлично, там я нашёл такой продукт как pldoc, это упрощённый аналог джавадок, это очень неплохо.
Но начальство требует ещё и блок-схемы по pl/sql, а я смотрю, где это делать, в визио или уже по-серьёзному, в какой-то uml-среде вроде визуал парадигмы...

я рисовал блок-схемы в Corel Draw, Adobe Illustrator, Word, Powerpoint,  Visio, Rational Rose, Sparx, Aris... (Visual Paradigm, честно, не смотрел) по-моему, лучше PlantUML нет ничего. При этом надо примерно следовать стандарту, смело отклоняясь от него, где надо. Хотя все, что касается художеств... очень субъективно

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

Художества, да, субъективное... поэтому я и смотрел в сторону юмл, всё-таки стандарт... но уж больно громоздок)

Да, я так понял, что plantuml надо посмотреть с пристрастием, раз его все так рекомендуют, это интересная штуковина!

Скорее UML-диаграммы заставляют осмысливать алгоритм по-другому. Да, это огромный путь. Но gain —  возможность точнее, нагляднее и компактнее показывать значимые для алгоритма элементы. Ведь все равно самое детальное описание алгоритма — это код. И правильно написанный код читается очень неплохо. И даже правильно написанный код на PL/SQL)) читается неплохо. Вопрос в том, как минимизировать усилия на постановку задачи. Хочется пройти максимальный путь до кода. Но только, чтобы этот путь был все-таки значительно легче кодирования. И опять же хочется, чтобы то, что написано, хорошо сопровождалось. Но усилия на написание хорошо документированного приложения не должны быть больше усилий, необходимых для прочтения и понимания кода. И разработчики UML эти вопросы видели. И, насколько это возможно, на них ответили.

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

ох,  хорошо же кому-то, если возможно сделать UML, а по нему написать код =)

+ к plantuml, ER диаграммы там прекрасно рисуются и поддерживаются, да и куча полезных других диаграмм также, там можно любую и блок схему нарисовать, не обязательно только uml, да и на uml лучше смотреть, действительно хороший инструмент проектирования, если действительно им пользоваться

Да, спасибо, что подключили к теме)
Сейчас получаю удовольствие от связки vs code + plantuml плагин!
Тупо подгрузил туда код и меняю его куски на операторы uml-языка)

Кайф, респект!

Терь это все версионировать и какой-нить CI и всё!

а вот такой вопрос - есть ли утилита, которая сможет проверить корректность команд градла, которые будут представлены в качестве примеров в README.md? Что-то вроде doctest, но для градла=)