Парни, всем привет! С ростом отделов проектов сталкиваемся с отсутствием/неактуальной документацией. Есть тут сомнения разные, "зайдет не зайдет", "протухнет", "а что писать". Знаю профит будет, дьявол в деталях. Есть роль тех писателя у кого профитная? Поделитесь опытом

В одной компании получилось сделать микрокурсы про документирование. Собрали тимлидов и продвинутый техпис рассказал на примерах, какие виды документации существуют и так далее. Не все зашло, не все было воспринято, но девелоперы стали писать документацию лучше и красивее. А вот с "глобальной" документацией - имхо это нерешаемая задача вообще. Сколько не подходили - практически напрасно выкинутое время/деньги.

мы юзали swagger, как минимум нет проблем с протуханием документации

сваггер это для апи. а как быть с документированием логики?

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

но кого это в наше то время волнует и останавливает !? 😂😂

Бхахахахахаха. А потом эти же люди смеются, когда в госах реализуют IT-проекты уровня Олимпиады.

Какой конкретно логики?

confluence. Но использовали это только когда новый человек приходит на проект

Это САМЫЙ худший выбоо из всех возможных

да ладно, есть еще куча вариантов хуже - листочек, notepad, word-файл, репост переписки, раскапывание тасок в Jira

Предложите лучший

Mediawiki, например

По крайней мере, там нет проблем с подсветкой кода и редактированием текста.

Потому что в конфлюэнсе нет и этого.

Подсветка кода есть
Как и редактирование текста тащемта

не-не, я не про инструмент. Я про процесс. тот же сваггер требует (ну ок, мягко), что бы описание было к методу. А конфлюенсу пофиг, что в него запихают.

эээ, куда сперли? там {code} вроде работало еще в незапамятные времена. и даже язык вроде можно было указывать ...

Ага, «работало».

И plantuml есть

Есть там подсветка кода.
Код в макрос "Код" закидываешь, выбираешь язык программирования и полетели.