С чего начать документирование существующего проекта?

[Владимир РунецПодписчик]

Вопрос навеян практикой.
Есть большой развивающийся проект, документация к которому находится в "обрывочном" состоянии: есть документы по отдельному функционалу, вносимым изменениям и улучшениям, но нет единой документации, по которой можно понять, что же представляет собой проект в целом.

Проект представляет собой веб-приложение. Обдумывая вопрос, вынесенный в заголовок — с чего начать документирование существующего проекта? — я для начала выделил основные логические разделы приложения:
1) каталог продукции
2) контент, создаваемый пользователями (комментарии, отзывы, сообщения на форуме, объявления)
3) контент, создаваемый редактором (статьи, новости)
3) функционал, доступный зарегистрированным пользователям (различный набор функций для различных типов пользователей)
4) административная часть для технического управления всем приложением.

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

Вопросы же следующие:
1) при таком делении раздела возникает проблема описания взаимосвязей данных разделов. Напримерм, комментарии можно оставлять как в каталоге продукции, так и в статьях и новостях, сообщения оставляются на форуме, но выводятся на странице новостей и т.п. Как это правильно организовать?
2) если же первые шаги не верны, то с чего нужно начинать, документируя существующий проект?

P.S. Если из такого краткого описания не совсем понятно, что же представляет собой проект, предлагаю взять за пример всем известные tut.by или onliner. С чего бы вы начали документирование подобных проектов?

Поделиться:

Цитировать

[Юрий ВеденинАдмин]

Вопрос разнесения спецификации по разным документам — это всего лишь вопрос удобства использования. Я думаю, что твой вопрос немного в другом: как осуществить грамотную разбивку спецификации на части? Как будут представлены части — в виде отдельных документов, пакетов документов, или просто в виде отдельных частей одного и того же документа — это вопрос удобства использования (поддержки документации и её чтения).
Может, уже одно то, что ты поймешь, что твой вопрос в другом, уже поможет тебе с ответом . Ведь даже если есть взаимосвязи между описываемыми частями, то в чем проблема вынести эти взаимосвязи в исходном документе в отдельную "главу"? А если речь идет про "отдельный документ для каждой отдельной части системы", то добавь, например, еще один документ для описания взаимосвязей..
В любом случае, твоя задача — это задача "кластеризации" (гугл ит за деталями). Тебе надо выделить в множестве требований группы. Внутри этих групп взаимосвязей много (потому они и группы), а между группами — либо мало, либо нет. Причем вероятность второго варианта (когда связей между группами нет) стремится к нулю.
Я приведу тебе пару примеров, чтобы тебе стало понятнее:

· модуль User Management (Authentication, Authorization, Manage Users, etc.), хоть и может являться самостоятельной группой требований, будет пронизывать тебе всю систему насквозь и будет связан с остальными модулями
· модуль Site Administration с одной стороны представляет собой отдельную часть системы, а с другой — скорей всего, каждый отдельный модуль будет иметь свою административную часть, которая будет представлена в Site Administration

Так что из лично моих советов всего три :

· попробуй разбивку не на документы, а на части одного документа
· попробуй вынести информацию про связи "групп" в отдельную часть документа или в отдельный документ
· попробуй другую разбивку требований на "группы"

На самом деле, вопрос требует более детального ознакомления с сутью проблемы. А так можно давать только общие рекомендации. Такое вот мое имхо…

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

Поделиться:

Цитировать

[Герман ШестеровАдмин]

Весьма часто встречающаяся ситуация… Специфицирование уже разработанного проекта.
Я начну, если не против, с последнего предложения — документирование tut.by или onliner.
Шаги:
1) Внимательный проход по приложению и разработка юз кейсов на основе его использования.
2) На основе полученных знаний анализ модульности приложения и разбиение документации на ряд спецификаций.
3) Набросок шаблонов каждого документа исходя из используемых тобой/в компании темплейтов.
4) Предварительное заполнение тех секций, которые можно заполнить исходя из простого использования приложения в качестве юзера.
5) Критически важное условие: наличие исходников проекта. Их отсутствие привносит огромные риски для валидности требований. Если они есть, то привлекается девелопер, который парсит исходный код (к примеру проходит по юз кейсам) и идентифицирует требования и логику, не видную глазу.
6) Верификация SRS, по возможности, у заказчика.

Поделиться:

Цитировать

[Юрий ШамрейПодписчик]

Господа, так и не узрел главного вопроса, "а что надо Заказчику"? =)

Поделиться:

Цитировать

[VitrimakПодписчик]

Присоеденюсь к прошлому посту, но позволю сформулировать так: "А какая цель документирования?" Вполне может быть, что цель — написать 1000 страничный документ, чтобы выбивать бюджеты у бюрократов и толстота документа будет весомым аргементом в пользу того, как много нужно делать и поддерживать.

Поделиться:

Цитировать

[Автор]

Сообщения