Выделение ресурсов для проектной документации
Что бы вы посоветовали для следующего сценария:
Десятке разработчиков нужно создать и спроектировать сложную систему. Этот проект должен быть задокументирован для будущих разработчиков, и проектные решения должны быть отмечены. Эти отчеты необходимо составлять примерно каждые два месяца. У меня вопрос в том, как оформить этот проект.
Я вижу две возможности. Каждый разработчик пишет о вещах, которые они помогли разработать и интегрировать, а затем один человек объединяет каждый из этих документов вместе. Окончательный документ, вероятно, будет временами непоследовательным или избыточным, поскольку у человека, которому поручено собрать все, не будет много времени, чтобы настроить каждую часть.
Предположим, что части документации от каждого разработчика прибывают всего за несколько дней до крайнего срока. Система для совместной работы (например, вики) не будет работать должным образом, так как не будет ничего, что можно было бы прочитать, пока не было сделано несколько дней до крайнего срока.
Или следует поручить нескольким людям (2-3) написать документацию, в то время как остальная часть команды будет работать над реальной разработкой системы? Разработчикам потребуется способ передать свои дизайнерские решения и выводы техническим писателям. Как это можно было сделать эффективно?
Ответы 5
Думаю, вы можете использовать Sand Castle для документирования своего проекта.
Проверить это
Это не полная документация, но проверка того, что интерфейсы и т. д. Комментируются с помощью Комментарии в стиле Doxygen, означает, что написание кода и его документирование ближе друг к другу.
Таким образом, разработчики должны документировать то, что они делают. Я по-прежнему считаю, что обзор со стороны архитектора (-ов) необходим для обеспечения постоянного качества, но обеспечение того, чтобы люди документировали то, что они делают, - лучший способ гарантировать, что они следуют архитектуре.
Мы используем слияние (атласская вики-подобная штука) и документируем всевозможные «вещи». Разработчики делают это постоянно, и мы подталкиваем друг друга к документации - мы позволяем давлению коллег решать, что необходимо. Всякий раз, когда появляется кто-то новый, ему / ей ставят задачу все прочитать и выяснить, что остается правильным. Вследствие этого неправильный материал либо удаляется, либо обновляется. Мы счастливы, когда можем удалять вещи;)
Хорошая вещь в этом процессе - то, что релевантный материал остается, а нерелевантный удаляется. Мы всегда «уходили» от более формализованных требований, заявляя, что всегда можем создать текстовые документы, которые им нужны, если они «им» понадобятся. «Они» в них никогда не нуждались.
Я думаю, что альтернатива 2 менее гибкая, потому что это означает новый этап проекта (хотя он может быть параллельно с тестами).
Если вы используете гибкую модель, просто добавьте документацию (следуя руководству) как рассказ. Если вы используете поэтапный подход, я бы все же попросил разработчиков поработать над документацией, следуя некоторым рекомендациям, и просмотреть эту документацию вместе с дизайном и кодом. В конце концов, у вас может быть технический писатель, который все проверяет на предмет правильного английского, но это будет своего рода «выпуском».
Мы подходим к этому с двух сторон, используя подход в стиле RUP. В первом случае у вас будет эксперт в предметной области, который будет отвечать за черновой дизайн того, что вы собираетесь поставлять, - при необходимости, разработчики вносят свой вклад. Во втором случае мы используем технического автора - они документируют приложение, поэтому они должны иметь хорошее представление о том, как оно работает, и вы вовлекаете их в процесс проектирования и разработки. В этом случае они могут помочь доработать дизайн и убедиться, что он соответствует тому, что, по их мнению, разрабатывается.