Идеальная система документирования

>Должны быть возможности готовить из этого формальные документы.
Выбирай: http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

С таким подходом вообще нужно две отдельные профессии - программист и комментатор кода.

две отдельные профессии - программист и комментатор кода

Пять с половиной:
- бизнес-аналитик (цели разработки)
- архитектор (архитектура системы)
- системный-аналитик (требования на разработку)
- программист (комментирование кода)
- технический писатель (документация пользователю)
- руководитель проекта (документация заказчику)

Выбирай

Я имел в виду как построить систему разработки из нескольких продуктов. Чтобы там было все необходимое. Т.е. типа trac + связки с VCS, генераторами, поисковиком и т.д.

Может какие другие варианты есть.

что-то вроде code.google.com?

Doxygen вполне хватает

> Что опенсорсное и какими способами могли бы использовать Вы, если бы хотели сделать максимально качественно?

Написал бы заново. Причём всё вместе: язык, компилятор, систему документации, вики, контроль версий и прочее. Потому что все делают как им захочется, никаких стандартов нет, а большинство таких систем — костыли (тот же Doxygen).

Literate programming, WEB/CWEB

> Literate programming, WEB/CWEB

Это, если проект ведешь ты единственный разработчик в команде.

http://sphinx.pocoo.org/

Единственный, маленький минус — генерация документации из кода ориентирована на python. Но это решается, пишу сейчас конвертер из doxygen xml в rst.

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

Пробовали раньше писать в wiki, но как-то не сложилось. Дурацкий язык разметки, неудобные html контролы. В общем, писали только самые сознательные товарищи. Остальные втихушку саботировали.

Сейчас, при коммите кода в репозиторий, если к нему есть документация, то генерируются html странички, и выкладываются на док-сервер. От разработчика требуется минимум усилий. И документация начала потихоньку появляться! Примеры использования, введение в предметную область модуля, красиво оформленное, с подсветкой синтаксиса, с индексом и поиском. Лепота.

ну книжки популярно по двое-трое писать, хотя больше чем по трое писателей не встречал :)

больше чем по трое писателей не встречал :)

http://www.ozon.ru/context/detail/id/2457392/
ну ты понял :)

>Приемы объектно-ориентированного проектирования. Паттерны проектирования

Design Patterns: Elements of Reusable Object-Oriented Software

Переводили тоже вчетвером наверное )