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

0

1

Как по вашему должна работать и из чего состоять идеальная система документирования в процессе разработки?

Вот тут написано, что можно писать Java-комментарии
http://www.kalinin.ru/programming/cpp/30_08_00.shtml
и затем обрабатывать их при помощи JavaDoc и Doxygen

Но совершенно очевидно, что этого недостаточно,
должно быть еще что-то типа wiki проекта для статей,
что-то для ведения глоссария,
какая-то утилита документирования базы данных

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

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

Ссылка

←	Вопрос про zImage собранный с опцией CONFIG_INITRAMFS_SOURCE

[QT] изменение значения в ячейке

→

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

fluorite ★★★★★
(21.02.10 20:41:35 MSK)

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

Siado ★★★★★
(21.02.10 20:57:28 MSK)

Ответ на: комментарий от Siado 21.02.10 20:57:28 MSK

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

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

~~ArsenShnurkov~~ ★
(21.02.10 21:36:46 MSK) автор топика

Ссылка

Ответ на: комментарий от fluorite 21.02.10 20:41:35 MSK

Выбирай

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

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

~~ArsenShnurkov~~ ★
(21.02.10 21:39:51 MSK) автор топика

Ответ на: комментарий от ArsenShnurkov 21.02.10 21:39:51 MSK

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

fluorite ★★★★★
(21.02.10 21:48:42 MSK)

Ссылка

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

Divius ★★
(21.02.10 21:49:49 MSK)

Ссылка

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

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

~~vkos~~ ★★
(21.02.10 21:56:35 MSK)

Ссылка

Literate programming, WEB/CWEB

yoghurt ★★★★★
(21.02.10 22:25:30 MSK)

Ответ на: комментарий от yoghurt 21.02.10 22:25:30 MSK

> Literate programming, WEB/CWEB

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

anonymous
(21.02.10 23:07:49 MSK)

http://sphinx.pocoo.org/

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

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

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

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

~~baverman~~ ★★★
(22.02.10 04:01:48 MSK)