LINUX.ORG.RU

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


0

1

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

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

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

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

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

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

Siado ★★★★★
()
Ответ на: комментарий от Siado

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


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

ArsenShnurkov
() автор топика
Ответ на: комментарий от fluorite

Выбирай


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

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

ArsenShnurkov
() автор топика

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

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

vkos ★★
()

http://sphinx.pocoo.org/

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

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

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

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

baverman ★★★
()
Ответ на: комментарий от ArsenShnurkov

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

Design Patterns: Elements of Reusable Object-Oriented Software


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

Siado ★★★★★
()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.