Вот толкового анализатора, который бы показал, что код обновился, а доки отстали — нет.

Анализ того, что код соответствует стандартам (например, о покрытии документацией), это работа lint'ера кода

Туда же, но про JS
https://eslint.org/docs/rules/require-jsdoc

И подобное нужно под все платформы, на чем код

Проблемы возникают, когда по каким-то причинам исходник документации лежит отдельно от источника истины – исходного кода

Зачем разносить, я аргументов не знаю, интересно бы послушать)

видимо, вопрос ко мне 🙂
Вы совершенно правы если смотреть на ситуацию со стороны техрайтера. Сохранять документацию можно и нужно, как вы правильно заметили, как можно ближе к источнику истины, к исходникам.
Если посмотреть со стороны инженера, и допустим мы делаем доки прямо в коде (и проверяем линтерами которые указаны выше), то инженер рискует получить портянку текста, в котором 80% доки, 20% код. Оно отлично, что java-doc есть — в 99% его или нет, или это текст типа “method get-user-id returns user id”. Но когда инженер с кодом знаком, такой текст ему только мешается. Когнитивная нагрузка только возрастает.
Плюс сюда добавляются проблемы, если в качестве доки у нас какая-ть pdf-ка с customer requirements, картинки с дизайном или файл на гуглодоке.
Если смотреть со стороны ПМа, то ситуация тоже получается не очень радостная. Как в таком случае ответить на вопрос “где доки к релизу 1.0?”
Мы предлагаем альтернативный (и ясное дело не единственно верный) подход, когда дока всё так же крепится к коду, только на нашей стороне. Получается, что и код не замусоривается, и прикрепить можно всё что угодно, и найти в пару кликов, и пометить доку как “к релизу 1.0”, и еще relevance factor получить автоматически

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

2. Пометки вида "к релизу 1.0" для доки делает git. Сами собой хеши коммита, и по науке git tag.

Как ваш инструмент решает проблему с комментами вида "method get-user-id returns user id"?
Что вы называете "relevance factor"?
Для чего и куда вы прикрепляете исходные PDF с общей постановкой?

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

Кстати, про процесс для ПМа тоже не понял

Подшивать внешние доки к версиям нужно вручную, верно? Если да, чем это отличатся от раздела на конфлюенсе с набором ссылок, куда тоже приходится вручную всё собирать?

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

ок, значит не ваш кейс.

> Пометки вида "к релизу 1.0" для доки делает git. Сами собой хеши коммита, и по науке git tag.

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

> Как ваш инструмент решает проблему с комментами вида "method get-user-id returns user id"?

Никак. Это не наша работа. Если инженер хочет оставить такую доку — его право. Кажется, такой код не пройдет code review

> Что вы называете "relevance factor"?
Релевантность ранее добавленной доки на сегодняшний момент. Например, выкатывали новый лендинг, в качестве доки прикрепили дизайн. Потом прошло 100 хотфиксов этой вёрстки, а дока не обновлялась. Вот мы даём понять, на сколько такой доке можно доверять по состоянию на сейчас.

> Для чего и куда вы прикрепляете исходные PDF с общей постановкой?
Простите, не понял вопроса.

> Подшивать внешние доки к версиям нужно вручную, верно? Если да, чем это отличатся от раздела на конфлюенсе с набором ссылок, куда тоже приходится вручную всё собирать?

“Подшивать” или нет — дело ваше. Вместо построения сложных иерархий, мы даём возможность тегирования. С помощью тегов удобно, например, собирать доки к очередному релизу

All you need is code, code, code.
Code is all you need.

Всё-as-a-Code

Мы привыкли, что артефакты для большинства стадии разработки ПО (SDLC) можно представлять в виде кода: тесты как код, инфраструктура как код, документация как код (@docops), архитектура как код, мокапы как код (https://imagineui.github.io/ru/). Потому что в таком случае к этим артефактам применимы все те же подходы, которые используются для кода: версионирование, ревью, автоматические проверки и т.д. Казалось, что требования к ПО были последним бастионом в этом движении, но с doorstop пал и этот бастион и теперь даже системные требования превратить в код. Каждое требование - отдельный файл в формате YAML, есть интеграция с Python.

Кстати требования для самого инструмента описаны в виде требований doorstop - https://github.com/doorstop-dev/doorstop/tree/develop/reqs

Презентация - https://speakerdeck.com/jacebrowning/doorstop-requirements-management-using-python-and-version-control

Ничего не понял по ссылке. Возможно какая-то особая предметная область?

Все как код, кроме самого кода, как мы шутили недавно с разработчиками

А код мышкой накидывать. Или диктовать AI: «хочу летучий корабль, чтобы...»

Насколько я понял, смысл в том, чтобы фичеветку начинать с файлика, в котором описаны требования к фиче. И у этих файликов строгая структура, так что они выстраиваются в иерархию и можно трассировать требования.
В доке больше написано: https://doorstop.readthedocs.io/en/latest/

Возможно меня смущают странные аббревиатуры srd, htlc

Непонятно что это такое и как эти концепции сопоставляются с привычными мне понятиями

Ага, меня тоже смущают. Это называется «проклятие знания». Авторы тулзы и документации к ней живут в мире, где все знают про SRD и HTLC.

Подозреваю, что это Software Requirements Document и High-level Test Case. В кодовой базе вообще нет этих сокращений, так что это просто какие-то умолчания. Можно писать doorstop create XYZ.