Делаем с помощью
notion.so - храним там базовую документацию, глоссарий понятий, очень краткие описания административных процедур, объяснения почему и как работают некоторые вещи, и конечно - документы на отдельные задачи (если задача крупная и писать полное описание в баг-трекере неудобно). Важно, что с этими документами работает сторона клиента, то есть они сами пишут задачи, вставляют туда скриншоты, etc. После чего написанное ими можно доработать, добавить разъяснения для разработчика - и в процесс.
Но вопрос документации в коде, о котором тут писали, меня сильно беспокоит; нам надо озаботиться этим. Именно для того, чтобы разработчики, особенно новые, видели в более понятном виде общую картину. Конечно, есть какая-то навигация в IDE, но всё равно это не вполне то.
Всю документацию держать в коде нельзя, по моему мнению, поскольку мы хотим привлечь клиента к работе над ней. Но и для разработчика отдельно писать код и отдельно доки - тоже проблема, лишние затраты времени и переключение контекста. Делать это никто не любит. Поэтому и думаю, что нужно иметь два комплекта документации - сугубо для разработки, автогенерированная из кода, и в базе знаний, ориентированная на клиента. Notion мне в этом смысле нравится неимоверно, ничего подобного в других местах я не видел. Хотя нет предела совершенству и хочется ещё большего :)
P. S. Евгений: по поводу literary programming... я пробовал нечто подобное делать в студенческом хобби-проекте, баловался. Но не очень получилось, поскольку линейная последовательность документа вступает в конфликт со структурой программы, имеющей вид графа.
Однако, мне доставляло изрядное удовольствие, что в результате получается не только код на Python, но и неимоверно красивый PDF, сделанный LaTeX, с картинками и формулами. А если исхитриться - можно ведь и прямо из кода всякие картинки генерировать, схемы БД например; красиво ведь будет. Надо как-нибудь вернуться к этой теме, очень уж она интересна.
Средний
