В каком формате вы пишете документацию к своим проектам?

Зачем нам документация, когда наш программист, который этот код написал, и так всё знает?

Для хранения документации используем конфлюенс, так что формат местный.

Затем, чтоб когда ваш код будет использовать не ваш программист, то икалось поменьше ;)

Интересуюсь потому, что сам подумываю начать писать полноценную.

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

Генерирую из исходников doxygenом.

Руководству расскажи.

У нас wiki отдельная, туда что-то доносится, когда доносится.

Когда код будет использовать не их пограмист, то закинут весь код в ИИ, чтобы нарисовал документацию для нужд стороннего пользователя )

Вот это, кстати, самый нормальный вариант. Главное не забывать её писать в процессе сразу, и думать не надо.

Да, хороший способ. Говно получится в любом итоге, что с ИИ, что без документации.

Генерирую из исходников doxygenом.

Никогда не использую так как AssistX поможет получить ответ на конкретный вопрос.
Да и в IDE и текстовых редакторах для программистов обычно бывает аналогичный функционал.
Конечно это моё субъективное мнение.

Документация - для слабаков.

Никогда не писал и не собираюсь

//Я сам себе руководство.

Моё руководство считает, что пора начать искать варианты документировать проект. Ибо были уже случаи, когда возвращался к коду, который писался очень давно и уже не могу разобраться, как он работает. Поэтому на будущее планируется расписывать более-менее сложные алгоритмы человеческим языком. Хотя бы в общих чертах.

Поэтому на будущее планируется расписывать более-менее сложные алгоритмы человеческим языком. Хотя бы в общих чертах.

Безусловно.
Иначе будет - «Не знал да ещё забыл».

И у тебя никогда не было такого, что открываешь свой же код через год и такой «Что за дебил это писал? Как оно работает?»?

Я знаю, кто это писал, поэтому таких вопросов не возникает

Markdown. Не вижу ни малейшего смысла выпендриваться здесь с чем-то экзотическим.

Моё руководство считает, что пора начать искать варианты документировать проект.

Бывает, что программисты специально не добавляют комментарии, … (понятно почему они так делают).

Markdown по работе, для себя иногда org-mode. Он по сути то же самое, но помощнее, плюс как айпайтон ноутбук работает, удобно иногда сгенерить конфиги и запустить деплой сразу из файла с докой.

Потому что код - лучшая документация.

открываешь свой же код через год и такой «Что за дебил это писал? Как оно работает?»?

Практически всегда.

Иногда ещё добавляется «Что за дебил писал документацию, которая противоречит коду?»

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

Фишка в том, что всегда нужна как минимум обзорная документация, чтоб тот, кто планирует пользоваться кодом, знал, что в нём вообще есть и как делается то или это.

Потому что код - лучшая документация.

Ага, если пол года его копать будешь …

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

Да, это мем скорее, в сложном проекте определенно нужна дока, где что лежит и как работает на верхнем уровне. А вот комментарии сомнительная штука, меня больше всего забавляет, когда пишут в таком стиле:

# проверяем что x > 0
if (x > 0) { ... }

Особенно это LLM часто делает

Использую HTML. Начал давно. Не переводить же теперь всё на markdown (чтобы что?), поэтому так в HTML и продолжаю. HTML это мейнстрим. markdown - лентяйская нишевая поделка. Вот когда браузеры начнут отображать markdown массово, тогда и подумаю. Можно вставлять .svg-картинки (или просто как фрагменты HTML). В таких картинках тоже можно делать участки гиперссылками.
Сегодня узнал про новую фичу, уверен, что markdown так не умеет, а фича полезная.

Вот когда браузеры начнут отображать markdown массово

браузеры

Мне изначально не понравилась идея запускать браузер для просмотра документации. Поэтому я для себя выбрал Marker. В нём посмотреть можно и в нём же отредактировать.

я для себя выбрал Marker

сложно его будет «продать» (убедить использовать) другим людям. А браузеры - легко.
Редактировать сторонние люди ничего не будут. Даже читать можно заставить с трудом, по себе знаю.

Единственная альтернатива - это .pdf (потому что в HTML нет страниц A4)

в последнее время пробую на asciidoc - умеет в pdf, html статик через hugo, например лаконичная тема https://github.com/alex-shpak/hugo-book

не решенная проблема - как бы этим заставить пользоваться других технических писателей конторы, которые умеют только «docx», чтобы не делать копипасту правок

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

Никак, только сделать движок для сайта, по аналогии с википедией, но другой. И даже после этого заставить будет тяжело.

Особенно это LLM часто делает

LLM это сделает не от балды, а при исправлении твоей ошибки в предыдущих итерациях. А дальше проблема человека что это ненужное тянет и дальше

Doxygen. Потом генерится во что угодно (у нас даже автохост сайьа с ним на работе).

Плюсы - дока всегда актуальна

Для текстов по типу readme — markdown/org-mode.

Для исходников — doxygen/qthelp, doxygen распространён, есть разные тулзы для конвертации, можно генерить оффлайн docset'ы для Zeal, у Zeal удобный поиск, но с генерацией docset'ов заморочки. Как альтернатива есть Qt Help, там всё из коробки, можно сразу доки сгенерить и просматривать в Qt Assistant, и есть встраиваемый виджет для просмотра.

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

readme в org, конвертирую в markdown, РЭ - в latex, к коду встроенная в язык или doxygen

Пишу обычно readme.txt . но у меня проекты маленькие.

txt

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

Получится ровно то, что ты напишешь.

Документация для слабых духом! Только код, только хардкор!

Документация должна объяснять в первую очередь идеологию работы твоего софта, без привязки к конкретным деталям кода. Справочник по коду - уже вторичен к этому. Если ты будешь это всё сувать в исходники, они станут замусоренными и неудобными с точки зрения кодинга. Точно так же, как сам код дробится на отдельные файлы разной специализации, надо и разделять документацию с кодом.

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

К примеру взять исходники PostgreSQLи попробовать понять его архитектуру всего проекта и подсистем без документации можно?
Можно.
Если пол года своей жизни на это потратить.
Впрочем конечно и профит от этого будет.

Пошучу

Но проектов много.
Тогда о таковых можно сказть - «Перед смертью он прекрасно понимал архитектуру PostgreSQL».

Другим такого не желаю …

У меня вот не было. Разве что свой очень старый код, когда я пользовался С++-ными фичами типа перегрузок функций и объявления переменных в середине кода, теперь осуждаю. Но хоть читать его не совсем комфортно, вопросов «как оно работает» всё же не возникает.

Документация не нужна.

На работе заставляют писать в местной Вике (Конфлюенс, как правило). Для своих поделок есть manы.

Задача ведь не только в том чтобы написать документацию к существующему коду, но и в том чтобы поддерживать в актуальном состоянии

Это да. Но так или иначе, документацию всё равно придётся обновлять руками, поэтому сначала хочу выбрать способ документации, а потом уже буду решать вопрос поддержания её в актуальном виде.

По работе markdown для репозитория (ибо сразу можно читать в браузере, с форматированием, ссылками и картинками) и wiki (confluence) с draw.io для всяких бизнес и архитектурных вещей. Sharepoint + excel / word / pdf для критической документации (аудит, комплаенс, disaster recovery и тд)

Для своих проектов как получится, но чаще всего несколько readme в маркдауне в репозитории.

Пару раз, когда ещё думал о ком-то, писал в обычном редакторе, сейчас нет, для себя заметки делаю и всё на этом.

README.md почти стандарт. Но есть нюансы. Где как выглядит простой

# Hello world for README.md

> [!NOTE]
> Hello from README.md

> [!WARNING]
> Don't use `README`, `README.txt`

Use shell session

`ShellSession`:

```ShellSession
[user@host:work_dir]$ echo 'Hello World!!!'
Hello World!!!
dir ls && cp

[user@host:work_dir]$ dir ls && cp
```

```ShellSession
user@host:work_dir$ echo 'Hello World!!!'
Hello World!!!
dir ls && cp

user@host:work_dir$ dir ls && cp
```

`shell-session`:

```shell-session
[user@host:work_dir]$ echo 'Hello World!!!'
Hello World!!!
dir ls && cp

[user@host:work_dir]$ dir ls && cp
```

```shell-session
user@host:work_dir$ echo 'Hello World!!!'
Hello World!!!
dir ls && cp

user@host:work_dir$ dir ls && cp
```

`console`:

```console
[user@host:work_dir]$ echo 'Hello World!!!'
Hello World!!!
dir ls && cp

[user@host:work_dir]$ dir ls && cp
```

```console
user@host:work_dir$ echo 'Hello World!!!'
Hello World!!!
dir ls && cp

user@host:work_dir$ dir ls && cp
```

gitea, github, obsidian, …. и тупо нет пересечения для ShellSession/shell-session/console * в скобочках или без. Но под конкретный выбрать можно.

По работе markdown для репозитория (ибо сразу можно читать в браузере, с форматированием, ссылками и картинками) и wiki (confluence) с draw.io для всяких бизнес и архитектурных вещей.

А почему например не в LibreOffice?
Те же возможности и много более …