powered by simpleCommunicator - 2.0.51     © 2025 Programmizd 02
Форумы / Разработка информационных систем [игнор отключен] [закрыт для гостей] / Документирование разработок, поддержание актуальности
25 сообщений из 30, страница 1 из 2
Документирование разработок, поддержание актуальности
    #37644129
PG81
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Наша организация разработала и осуществляет сопровождение и доработку нескольких АИС (Delphi 7-XE + MS SQL Server 2005), каждая из которых имеет отдельную БД. Между базами осуществляется достаточно активный обмен данными. Ведется доработка клиентов и БД, а так же устранение багов и глюков.

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

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

Почему раньше об этом никто не думал, потому что не было времени на это, нужно было все сделать уже вчера и не было ресурсов. Теперь есть ресурсы и необходимость.

Поделитесь опытом.
Кто как ведет разработку АИС? (любопытен опыт реально работающего сопровождения)
Как ведется документирование проектов? (хотябы на системном уровне для разработчиков )
Как поддерживается эта документация в актуальном состоянии?
Может пользуетесь какими-то специальными для этого приложениями?
Может свои внутренние разработки? Какие их основные принципы?
Используется ли как-то самодокументирование? (например, особые комментарии, которые потом попадают в документаццию)
Каким аспектам документирования уделяется особое внимание? (имеет смысл наверное описывать только самое важное, хотябы на первом этапе)
Отвечает ли за это специальные люди или отдел или разработчики самостоятельно поддерживают актуальность?
Имет ли вообще смысл вести системную документацию или может вообще разработку программ нужно вести определенным образом?

Зарание благодарен, кто подключиться к дискуссии.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37644150
LSV
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Лучше любой документации - качественное проектирование самого проекта. Когда сразу понятно, где проблема. :)
Не нужно рыться и трейсить.

StarTeam (приложение+SQL-скрипты) + Док-файлы документации для пользователей.

Вся логика в хр. процедурах SQL.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37644200
PG81
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
вся логика только в хранимках. Клиентское приложение только вызывает их выполнение.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37644238
Фотография Petro123
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PG81,
- метод XP
- ErWin печать на формат A0 + поля - Комментарий в таблицах + CVS
- только заставлять
- нет
- нет
- нет
- нет
- архитектор или тимлидер
- закрепить в регламенте в своей фирме
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37644740
kmaw
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PG81вся логика только в хранимках. Клиентское приложение только вызывает их выполнение.

спорно. БД может быть не одна, да и внешние сервисы могут использоваться
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37644789
kmaw
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
kmawPG81вся логика только в хранимках. Клиентское приложение только вызывает их выполнение.

спорно. БД может быть не одна, да и внешние сервисы могут использоваться

да и к документированию отношение не имеет.
главное, чтобы была собрана в одном месте вся проектно-эксплутационная документация по системе: ТЗ, всякие письма с пожеланиями/заданиями доработки, всякие переговоры кого-то с кем-то по поводу каких-то модернизаций, ТР, договора/контракты, регламенты, всякие важные мысли по поводу системы и т.д. Чтобы была понятна "в общем" предметная область и её текущее состояние.

Систематически вести такую "папку" - обязательно.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37645471
ЮВ
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PG81...вся информация о взаимосвязях содержиться в головах разработчиков, да и те забывают.

Да, это плохо. Если кто-то из них попал под трамвай, разобраться в исходных текстах бывает проблематично.

PG81Кто как ведет разработку АИС? (любопытен опыт реально работающего сопровождения)
Имет ли вообще смысл вести системную документацию или может вообще разработку программ нужно вести определенным образом?

Если планируется длительное сопровождение АИС с возможностью выпуска новых версий ПО и сопровождение выполняется не самим разработчиками (так и должно быть), а специально выделенными специалистами, то должна быть подготовлена документация сопровождения.
Требования к процессу сопровождения изложены, например, в ГОСТ РВ 0019-001 -2006, документ "План передачи программного обеспечения".

PG81Как ведется документирование проектов? (хотябы на системном уровне для разработчиков )

Это должно делаться соответствующими специалистами (разработчиками документации, "техническими писателями"),
потому что кредо программистов: "Читать документацию является признаком плохого тона, а писать её - тем более".

PG81Как поддерживается эта документация в актуальном состоянии?
Может пользуетесь какими-то специальными для этого приложениями?

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

PG81Может свои внутренние разработки? Какие их основные принципы?


Да, обязательно должны использоваться корпоративные стандарты, например, на оформление исходных текстов,
правила именования объектов БД и т. п.

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


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

PG81Отвечает ли за это специальные люди или отдел или разработчики самостоятельно поддерживают актуальность?


Как сказано выше, без специального ПО выполнять контроль за актуализацией изменений проблематично.
Если используется срециальное ПО, то для каждого внесенного в ПО изменения (зафиксированного в системе отслеживания изменений) есть ответственные лица за его актуализацию как в документации, так и в дистрибутиве и т. п., т. е. отследить этот процесс несложно.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37645577
DPH3
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
По опыту нескольких проектов:

Документация (и вообще база знаний) - ведется в корпоративной wiki. Выбор богатый: Confluence, MediaWiki etc

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

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

С течением времени к работе через общую вики приучаются и менеджеры/тестеры/постановщики. Но на это может уйти год и больше.

Для SQL я бы попробовал сделать генератор документации в вики-стиле (пакеты, таблицы, хранимки с комментариями специфического вида автоматически преобразовывать в вики-странички). Делов - не много, а пользы - дофига.

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

Документация всегда устаревает, главное - что бы это было не катастрофическое устаревание.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37645596
DPH3
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
DPH3,
Да, у меня проекты не выше D100 по матрице Коуберна. Если у вас что-то более ответственное, то и документирование требуется уже другое.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37645722
PG81
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
ЮВ,
Благодарю за развернутый ответ.
Вот некоторые уточнения.
Передавать ПО на сопровождение никому не планируется. Поэтому тут никакие стандарты учитывать нет необходимости, от ни нужно взятьтолько самое полезное.

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

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

специальных людей пока нанимать не планируется.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37645745
PG81
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
DPH3,

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

У меня еще такая идея возникла.

Может документацию разбить на разделы (например html страницы) и каждый раздел так же как и программные модули вести в TFS (аналог CVS)
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37646085
ЮВ
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PG81Передавать ПО на сопровождение никому не планируется. Поэтому тут никакие стандарты учитывать нет необходимости, от ни нужно взятьтолько самое полезное.

Стандарт содержит общие рекомендации по организации процесса сопровождения.
Требования нужно брать, естественно, с учетом свой специфики.
Но есть и обшие, например,
1 Ресурсы сопровождения
2 ПО, используемое в процессе сопровождения (типа контроль учета изменений) и инструкции работы с ним
3 Документация, используемая при сопровождении (перечислить все из написанного и пригодного)
4 Предполагаемые (планируемые) области изменений и др.

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

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

PG81действительно разработчиков сложно заставить ее постоянно заполнять. Особенно когда зменения незанчительные.

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

Повторяю еще раз: необходимость во всех этих работах полностью зависит от того, как долго планируется использовать АИС и как часто необходимо вносить в неё изменения.
А это все индивидуально.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37647262
Фотография Petro123
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
DPH3по матрице Коуберна
это шутка или поделитесь аналитикой на критерий?
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37647324
DPH3
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Petro123DPH3по матрице Коуберна
это шутка или поделитесь аналитикой на критерий?

Э, не понял, а в чем проблемы с пользованием матрицей? Размер команды обычно известен, риски для потребителей также несложно прикинуть. А уж что конкретные решения зависят таки от конкретного проекта - достаточно очевидно.
Ну нет смысла для проекта в D100 использовать тяжелые методологии и ГОСТы, созданные для проектов уровня D10000 или L100.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37647448
Фотография Petro123
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
DPH3в чем проблемы с пользованием матрицей?
:) дык кроме вас её тут никто не пользует. Или никто не пишет про использование.
Дайте поиск.
Есть ссылка на использование на доступном языке?
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37647971
DPH3
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Petro123Есть ссылка на использование на доступном языке?
Ну, само описание подхода - в статье http://www.maxkir.com/sd/methyperproject_RUS.htm
Я, похоже, излишне оптимистично, думал, что это такой же must read, как и Брукс или ДиМарко - вот и ссылаюсь.
Но тут посмотрел в яндексе - и, похоже, действительно, почти никто кроме меня не ссылается. А многие холивары в рамках этого подхода просто теряют смысл :)

Вообще, если есть другой вариант описания размера и сложности проекта - то я с удовольствием прочитаю. Но как-то ничего не встречал...
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37648013
DPH3
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PG81DPH3,
Может документацию разбить на разделы (например html страницы) и каждый раздел так же как и программные модули вести в TFS (аналог CVS)

По идее, документация будет состоять как из автоматически созданных частей, так и из документов, написанных разработчиками. В будущем - еще и постановки.

По моему опыту, лучше wiki-систем ничего не придумано. Там, кстати, и встроенная система версий есть и многое другое. Начинать стоит прямо оттуда.

Потом, например, можно добавить и автогенерацию документации по коммиту в TFS (надеюсь, там можно делать такое) - и тоже добавлять в wiki.

Делать все в TFS - не очень хорошо, учить не программистов работать с TFS - не слишком просто, а при развитии документации это потребуется.

Да, еще, из мелких советов: кроме обзора архитектуры очень советую завести документ "грязные хаки", где записывать все то, что пришлось делать из-за спешки или ошибок или еще чего-нибудь. Откровенное признание своих ошибок и уменьшает их число и позволяет потом их потихоньку исправлять. Да и знание очень полезное.

А вы в каком городе?
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37648112
Фотография Petro123
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
DPH3Вообще, если есть другой вариант описания размера и сложности проекта - то я с удовольствием прочитаю. Но как-то ничего не встречал...я тоже не встречал, поэтому спс. за ссылку - почитаю.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37648115
Фотография Petro123
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
DPH3советую завести документ "грязные хаки",
у программистов это "костыли"
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37648152
DPH3
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Petro123DPH3советую завести документ "грязные хаки",
у программистов это "костыли"

Ну, в вики эту страницу обычно называю Smells :)
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37648157
DPH3
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Petro123DPH3Вообще, если есть другой вариант описания размера и сложности проекта - то я с удовольствием прочитаю. Но как-то ничего не встречал...я тоже не встречал, поэтому спс. за ссылку - почитаю.

Хм, как прочитаешь - скажи, стоит ли по этому поводу, например, какую-нибудь статью написать. А то я содержимым статьи активно пользуюсь (а там есть некоторые тонкости, которые становятся заметны при практике). Или оно, в общем, нафиг никому не нужно?
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37648219
Фотография Petro123
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
DPH3Petro123пропущено...
я тоже не встречал, поэтому спс. за ссылку - почитаю.

Хм, как прочитаешь - скажи, стоит ли по этому поводу, например, какую-нибудь статью написать. А то я содержимым статьи активно пользуюсь (а там есть некоторые тонкости, которые становятся заметны при практике). Или оно, в общем, нафиг никому не нужно?
всем нужно - пиши.
Просто оценить и формализовать ЭТО очень трудно.
Я по прежнему считаю, что программирование - искусство, а архитектор - просто отсекает лишнее, как скульптор.
PS попозже почитаю, тут напишу.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37648455
Фотография softwarer
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PG81Кто как ведет разработку АИС? (любопытен опыт реально работающего сопровождения)
Я бы не стал отдельно выделять сопровождение. В нынешних условиях проще и правильнее считать, что все время жизни программы - одно длинное сопровождение. А как.. большой вопрос, что именно Вас интересует?

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

PG81Как поддерживается эта документация в актуальном состоянии?
Комментарии модифицируются вместе с кодом, а практика code review позволяет видеть недокомментированное и соответственно исправлять. Отдельная же документация в силу конструкции - краткое описание основ - редко нуждается в изменениях.

PG81Отвечает ли за это специальные люди или отдел или разработчики самостоятельно поддерживают актуальность?
Документацию для разработчиков не может поддерживать никто кроме разработчиков.
Если ведётся пользовательская документация - в хорошем случае соответствующие этапы просто включены в workflow трекера. То есть задача после аналитика, разработчика и тестировщика попадает к техпису. Но чаще, к сожалению, "всякая байда которую надо написать по договору и стандартам" пишется совершенно отдельно от процесса разработки и с соответствующим качеством.

PG81Имет ли вообще смысл вести системную документацию или может вообще разработку программ нужно вести определенным образом?
Факт в том, что чем качественнее делается разработка - тем меньше документации требуется.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37648460
Фотография softwarer
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
DPH3Для SQL я бы попробовал сделать генератор документации в вики-стиле (пакеты, таблицы, хранимки с комментариями специфического вида автоматически преобразовывать в вики-странички). Делов - не много, а пользы - дофига.
Пользы ноль, вернее сказать.
...
Рейтинг: 0 / 0
Документирование разработок, поддержание актуальности
    #37648466
Фотография kosh the best
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Ребят, вы чего? Что за бред тут понаписали в двадцати постах? Какая документация исходного кода? Какие вики по коду? Достаточно одного документика - так называемый "курс молодого бойца" с кратким введением что и как + документируется все внешнее api, протоколы и форматы передачи, торчащие из системы.
Ну и, естественно, должна быть налажена система контроля версий (svn, git желательно), в которой хранится все - код, скрипты, документация + продвинутый багтрекер с возможностью project management (ну или хотя бы просто багтрекер).
...
Рейтинг: 0 / 0
25 сообщений из 30, страница 1 из 2
Форумы / Разработка информационных систем [игнор отключен] [закрыт для гостей] / Документирование разработок, поддержание актуальности
Целевая тема:
Создать новую тему:
Автор:
Закрыть
Цитировать
Найденые пользователи ...
Разблокировать пользователей ...
Читали форум (0):
Пользователи онлайн (0):
x
x
Закрыть


Просмотр
0 / 0
Close
Debug Console [Select Text]