Каковы хорошие и плохие способы документирования программного проекта?

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

Что важно для документирования? Должна ли документация кода и дизайна в основном содержать код в виде комментариев? Должны ли мы помещать текстовые файлы или документы Word непосредственно в исходный элемент управления вместе с кодом? Должны ли мы использовать wiki?

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

Меня интересуют, какие подходы вы использовали в подобных проектах. Что сработало хорошо, что не получилось, и почему?

Некоторые ключевые факты о проекте:

Платформа - это С# и .NET.
Мы используем Visual Studio и Team Foundation Server для управления исходным кодом и управления рабочими элементами (задачами).
Мы используем Scrum и тестовую разработку и вдохновляемся дизайном, управляемым доменом.
Программное обеспечение состоит из набора веб-сервисов и двух графических клиентов.
Другие клиенты собираются интегрироваться с веб-сервисами в будущем. Интеграция будет выполняться другими разработчиками в других командах (поэтому веб-службы образуют своего рода API).
SharePoint широко используется во всей среде разработки. В большинстве проектов есть сайт SharePoint, в том числе наш.
На нашем веб-сайте проекта у нас в настоящее время есть куча документов MS Office по таким вещам, как требования, дизайн, презентации для заинтересованных сторон и т.д. Хранение всех в актуальном состоянии сложно.
У нас также есть вики-страница SharePoint для команды разработчиков, где мы документируем вещи неструктурированным образом по мере продвижения. Примеры включают, как организованы наши скрипты сборки, наша политика тестирования, рекомендации по кодированию.
Программное обеспечение - это собственное приложение в довольно крупном финансовом учреждении.
Программное обеспечение разработано командой из шести человек в течение ~ 1 года.
Разработчики - это консультанты, нанятые для этого проекта, и не будут доступны для помощи в будущем (если только клиент не решит заплатить за него).
У клиента несколько указаний о том, как этот документ должен быть документирован.

Ответ 1

Я думаю, что наиболее важными для документа являются решения. Это касается всего от требований к архитектурным решениям. Каковы требования модуля X? Как эти требования представлены в архитектуре? Почему вы выбрали архитектурный шаблон A над B? Каковы преимущества? То же самое касается исходного кода: общеизвестно, что комментирование того, почему путь лучше, чем способ.

Как вы документируете эти решения, не важно, на мой взгляд, независимо от того, используете ли вы Wiki или документ требований, созданный в Word. Более важно то, что эти документы всегда актуальны и что каждому легко доступ к ним. Это может быть достигнуто с помощью вики или размещения документов под контролем источника, как вы говорите. Если только некоторые из них имеют к ним доступ, они, скорее всего, не будут обновляться, а не будут прочитаны при необходимости.

Мы используем Wiki для нашего текущего проекта, и он работает очень хорошо. Легко получить доступ для всех (разработчиков, менеджеров и клиентов), и история может отслеживать изменения, поэтому вы знаете, что было изменено и почему. Кроме того, мы стараемся документировать код значимым образом и документировать основные проектные решения. Мы стараемся не документировать слишком много, например. второстепенные вещи, поскольку всегда трудно сохранить эти вещи в актуальном состоянии, и это не стоит усилий, imho.

Ответ 2

Хуже меня, чем отсутствие документации, - это превышение документации.

Имейте в виду, что да: действительно важно документировать ваш проект, но также и то, что основная часть вашей документации всегда подвержена риску никогда.

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

Ответ 3

G'day,

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

Вот пара начальных мыслей.

Категория:

Начните с начальной онтологии того, что вы хотите захватить, но

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

Tagging:

Начните использовать облако тегов. BTW здесь отличный плагин для TWiki, чтобы начать классифицировать контент на ранней стадии проекта. Повторная установка тегов практически невозможна. Начало ранжирования рангов также позволяет людям искать информацию, которая может быть там уже, а не иметь ту же информацию, что и в нескольких местах.

HTH Я вернусь и добавлю больше очков, поскольку я думаю о них.

Ответ 4

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

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

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