Внутренняя документация по продукту

Question

У нас есть система, которая выросла на протяжении ряда лет (ASP.NET Web Forms, MySQL), и мы ищем рекомендации относительно того, что документировать об этом и как документировать ее, чтобы у нас была мы можем разобраться, как должна себя вести система.

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

Мы разрабатываем всеобъемлющие модульные тесты, но это усилие все еще продолжается, и я не считаю, что модульные тесты будут хорошим и понятным описанием того, что делает система.

Как люди документировали функциональность и поведение системы? Какие инструменты вы используете? Кто несет ответственность за документацию? Вы организуете его по экрану? По сценарию?

Answer 1

Я нахожу Doxygen весьма полезным для документации. (Он поддерживает C#, если это тот язык, который вы используете.) Что касается того, кто несет ответственность, я считаю правильным ответ, что все разработчики должны нести ответственность. Doxygen (и многие другие инструменты документации) имеют опции для выдачи предупреждений для кода, который не документирован.

Любой разработчик должен всегда проверять, чтобы полный комплект документации можно было подготовить до совершения кода. Даже при довольно большом проекте это займет всего пару минут, чтобы проверить и разрешить. Это намного проще, чем заставить кого-то вернуться позже и попытаться выяснить, что происходит.

Answer 2

Я понимаю, что это старый вопрос, но MindTouch уже несколько лет разрабатывает решение (MindTouch TCS), которое подходит именно для того, что вы описываете. http://www.mindtouch.com/products/mindtouch_tcs

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