Выделение ресурсов для проектной документации [закрыто]

Что бы вы предложили для следующего сценария:

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

Я вижу две возможности. Каждый разработчик пишет о том, что они помогли спроектировать и интегрировать, а затем один человек объединяет каждый из этих документов вместе. Окончательный документ, вероятно, будет временами непоследовательным или излишним, поскольку у человека, которому поручено собрать все, не будет много времени для корректировки каждой детали.

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

Или несколько человек (2-3) должны будут написать документацию, в то время как остальная часть команды работает над реальной разработкой системы? Разработчикам потребуется способ передать свой выбор дизайна и выводы техническим писателям. Как это можно сделать эффективно?

13.12.2008 20:52:27
5 ОТВЕТОВ
РЕШЕНИЕ

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

1
13.12.2008 21:09:21

Я думаю, вы можете использовать Sand Castle для документирования вашего проекта.

Проверьте это

Песочный замок от Microsoft

0
13.12.2008 20:55:49

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

Таким образом, разработчики должны задокументировать, что они делают. Я по-прежнему считаю, что для обеспечения постоянного качества требуется проверка со стороны архитектора (-ов), но обеспечение того, чтобы люди документировали то, что они делают, - лучший способ убедиться, что они следуют архитектуре.

0
13.12.2008 21:01:39

Мы используем слияние (wiki-like-вещь от Atlassian) и документируем все виды «вещей». Разработчики делают это постоянно, и мы подталкиваем друг друга к документам - мы позволяем давлению со стороны коллег решить, что необходимо. Всякий раз, когда появляется кто-то новый, ему / ей поручают прочитать все и выяснить, что еще правильно. Вследствие этого неверный материал либо удаляется, либо обновляется. Мы рады, когда мы можем удалить вещи;)

Хорошая вещь в этом процессе заключается в том, что соответствующий материал остается, а ненужный материал удаляется. Мы всегда «уходили» от более формализованных требований, утверждая, что мы всегда можем составить слово документы, которые они хотят, если «они» нуждаются в них. «Они» никогда не нуждались в них.

1
13.12.2008 21:01:45

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

Если вы находитесь в гибкой модели, просто добавьте документацию (следуя рекомендациям) в виде истории.
Если вы используете поэтапный подход, я бы, тем не менее, попросил разработчиков поработать над документацией, следуя некоторым рекомендациям, и просмотреть эту документацию по проекту и коду. В конце концов, у вас может быть технический писатель, который рассматривает все на предмет правильного английского, но это было бы своего рода «выпуском».

1
13.12.2008 21:37:37