|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
Наша организация разработала и осуществляет сопровождение и доработку нескольких АИС (Delphi 7-XE + MS SQL Server 2005), каждая из которых имеет отдельную БД. Между базами осуществляется достаточно активный обмен данными. Ведется доработка клиентов и БД, а так же устранение багов и глюков. Системы достаточно динамично развиваются и растут. Когда это были десятки таблиц, хранимых процедур и программных модулей у клиента, а разработкой заимались несколько человек, каждый из которых практически в одиночку вел свой проект, то особых сложностей не возникало, чтобы например даже постороненму человеку разобраться в поставленной задаче и ее реализовать. Но с ростом количества таблиц БД, хп, модулей и т.д. становиться достаточно сложно вести дальнейшую разработку вводить в строй новых сотрудников, так как вся информация о взаимосвязях содержиться в головах разработчиков, да и те забывают. Комментарии в модулях уже не спасают, хотя их не так уж и много. Новым сотрудникам достаточно долго приходится въезжать в курс дела, просиходит отвлечение старожил, да и сам процесс разработки замедляется. Почему раньше об этом никто не думал, потому что не было времени на это, нужно было все сделать уже вчера и не было ресурсов. Теперь есть ресурсы и необходимость. Поделитесь опытом. Кто как ведет разработку АИС? (любопытен опыт реально работающего сопровождения) Как ведется документирование проектов? (хотябы на системном уровне для разработчиков ) Как поддерживается эта документация в актуальном состоянии? Может пользуетесь какими-то специальными для этого приложениями? Может свои внутренние разработки? Какие их основные принципы? Используется ли как-то самодокументирование? (например, особые комментарии, которые потом попадают в документаццию) Каким аспектам документирования уделяется особое внимание? (имеет смысл наверное описывать только самое важное, хотябы на первом этапе) Отвечает ли за это специальные люди или отдел или разработчики самостоятельно поддерживают актуальность? Имет ли вообще смысл вести системную документацию или может вообще разработку программ нужно вести определенным образом? Зарание благодарен, кто подключиться к дискуссии. ... |
|||
:
Нравится:
Не нравится:
|
|||
02.02.2012, 15:44 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
Лучше любой документации - качественное проектирование самого проекта. Когда сразу понятно, где проблема. :) Не нужно рыться и трейсить. StarTeam (приложение+SQL-скрипты) + Док-файлы документации для пользователей. Вся логика в хр. процедурах SQL. ... |
|||
:
Нравится:
Не нравится:
|
|||
02.02.2012, 15:51 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
вся логика только в хранимках. Клиентское приложение только вызывает их выполнение. ... |
|||
:
Нравится:
Не нравится:
|
|||
02.02.2012, 16:05 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
PG81, - метод XP - ErWin печать на формат A0 + поля - Комментарий в таблицах + CVS - только заставлять - нет - нет - нет - нет - архитектор или тимлидер - закрепить в регламенте в своей фирме ... |
|||
:
Нравится:
Не нравится:
|
|||
02.02.2012, 16:20 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
PG81вся логика только в хранимках. Клиентское приложение только вызывает их выполнение. спорно. БД может быть не одна, да и внешние сервисы могут использоваться ... |
|||
:
Нравится:
Не нравится:
|
|||
02.02.2012, 19:51 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
kmawPG81вся логика только в хранимках. Клиентское приложение только вызывает их выполнение. спорно. БД может быть не одна, да и внешние сервисы могут использоваться да и к документированию отношение не имеет. главное, чтобы была собрана в одном месте вся проектно-эксплутационная документация по системе: ТЗ, всякие письма с пожеланиями/заданиями доработки, всякие переговоры кого-то с кем-то по поводу каких-то модернизаций, ТР, договора/контракты, регламенты, всякие важные мысли по поводу системы и т.д. Чтобы была понятна "в общем" предметная область и её текущее состояние. Систематически вести такую "папку" - обязательно. ... |
|||
:
Нравится:
Не нравится:
|
|||
02.02.2012, 20:36 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
PG81...вся информация о взаимосвязях содержиться в головах разработчиков, да и те забывают. Да, это плохо. Если кто-то из них попал под трамвай, разобраться в исходных текстах бывает проблематично. PG81Кто как ведет разработку АИС? (любопытен опыт реально работающего сопровождения) Имет ли вообще смысл вести системную документацию или может вообще разработку программ нужно вести определенным образом? Если планируется длительное сопровождение АИС с возможностью выпуска новых версий ПО и сопровождение выполняется не самим разработчиками (так и должно быть), а специально выделенными специалистами, то должна быть подготовлена документация сопровождения. Требования к процессу сопровождения изложены, например, в ГОСТ РВ 0019-001 -2006, документ "План передачи программного обеспечения". PG81Как ведется документирование проектов? (хотябы на системном уровне для разработчиков ) Это должно делаться соответствующими специалистами (разработчиками документации, "техническими писателями"), потому что кредо программистов: "Читать документацию является признаком плохого тона, а писать её - тем более". PG81Как поддерживается эта документация в актуальном состоянии? Может пользуетесь какими-то специальными для этого приложениями? Полагаться на сознательность разработчиков, которые будут уведомлять об изменениях - наивно. Необходимо использовать специальные программные средства. Например, "Система управления рекламациями и изменениями ПО". Все внесенные изменения в ПО фиксируются в ней. Подписчики (пользователи, любые заинтересованные лица, в том числе, и разработчики документации) получают уведомления об изменениях с комментариями внесенных изменений. PG81Может свои внутренние разработки? Какие их основные принципы? Да, обязательно должны использоваться корпоративные стандарты, например, на оформление исходных текстов, правила именования объектов БД и т. п. PG81Используется ли как-то самодокументирование? (например, особые комментарии, которые потом попадают в документаццию) Каким аспектам документирования уделяется особое внимание? (имеет смысл наверное описывать только самое важное, хотябы на первом этапе) Самодокументирование (особенно если потом применяются специальные программные средства для подготовки документации на его основе) очень желательно. Но в добровольном виде трудно осуществимо. Как сказано выше, программисты всячески избегают этого. Но даже если начинают (из под палки) вносить комментарии, то число формально - их комментарии часто не приносят особой пользы. PG81Отвечает ли за это специальные люди или отдел или разработчики самостоятельно поддерживают актуальность? Как сказано выше, без специального ПО выполнять контроль за актуализацией изменений проблематично. Если используется срециальное ПО, то для каждого внесенного в ПО изменения (зафиксированного в системе отслеживания изменений) есть ответственные лица за его актуализацию как в документации, так и в дистрибутиве и т. п., т. е. отследить этот процесс несложно. ... |
|||
:
Нравится:
Не нравится:
|
|||
03.02.2012, 12:24 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
По опыту нескольких проектов: Документация (и вообще база знаний) - ведется в корпоративной wiki. Выбор богатый: Confluence, MediaWiki etc Документацию ведут сами разработчики, но тимлид должен контролировать этот процесс, показывать примеры, следить за структурой, в первое время - уговаривать делать. Затраты на документирование нужно планировать, а то в аврале на это времени не остается. В первую очередь нужны документы с описанием архитектуры системы, основных модулей, основных концепций. В дальнейшем там начнут появляться описания всех задач. С течением времени к работе через общую вики приучаются и менеджеры/тестеры/постановщики. Но на это может уйти год и больше. Для SQL я бы попробовал сделать генератор документации в вики-стиле (пакеты, таблицы, хранимки с комментариями специфического вида автоматически преобразовывать в вики-странички). Делов - не много, а пользы - дофига. Новые сотрудники на первую неделю сажаются за документирование какой-нибудь части системы. Так и они быстрее погружаются в предметную область, и для компании сразу польза. Документация всегда устаревает, главное - что бы это было не катастрофическое устаревание. ... |
|||
:
Нравится:
Не нравится:
|
|||
03.02.2012, 13:00 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
DPH3, Да, у меня проекты не выше D100 по матрице Коуберна. Если у вас что-то более ответственное, то и документирование требуется уже другое. ... |
|||
:
Нравится:
Не нравится:
|
|||
03.02.2012, 13:07 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
ЮВ, Благодарю за развернутый ответ. Вот некоторые уточнения. Передавать ПО на сопровождение никому не планируется. Поэтому тут никакие стандарты учитывать нет необходимости, от ни нужно взятьтолько самое полезное. Для контроля за изменениями используем TeamFoundationServer. Изменения там конечно отражаются, но по ним достаточно сложно сложно понять общую логику программы на конкретный момент времени. Кое что есть конечно в нашей Wiki, но с помощью нее достаточно не удобно вести документирование, да и действительно разработчиков сложно заставить ее постоянно заполнять. Особенно когда зменения незанчительные. специальных людей пока нанимать не планируется. ... |
|||
:
Нравится:
Не нравится:
|
|||
03.02.2012, 13:49 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
DPH3, Согласен с вами, что в первую очередь описывать нужно счамое важно а все остальное по мере необходимости как с этим будем сталкиваться. У меня еще такая идея возникла. Может документацию разбить на разделы (например html страницы) и каждый раздел так же как и программные модули вести в TFS (аналог CVS) ... |
|||
:
Нравится:
Не нравится:
|
|||
03.02.2012, 13:54 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
PG81Передавать ПО на сопровождение никому не планируется. Поэтому тут никакие стандарты учитывать нет необходимости, от ни нужно взятьтолько самое полезное. Стандарт содержит общие рекомендации по организации процесса сопровождения. Требования нужно брать, естественно, с учетом свой специфики. Но есть и обшие, например, 1 Ресурсы сопровождения 2 ПО, используемое в процессе сопровождения (типа контроль учета изменений) и инструкции работы с ним 3 Документация, используемая при сопровождении (перечислить все из написанного и пригодного) 4 Предполагаемые (планируемые) области изменений и др. PG81Для контроля за изменениями используем TeamFoundationServer. Изменения там конечно отражаются, но по ним достаточно сложно сложно понять общую логику программы на конкретный момент времени. Для контроля изменений используем собственную систему BugTracking (на уведомления об изменениях могут подписываться как внутренние пользоваттели - разработчики, так и любопытные внешние пользователи, естественно, с некоторыми ограничениями). В этом случае чтобы понять как вы пишите "логику программы на конкретный момент времени" надо смотреть хронологию (историю) изменений конкретной программы (это возможно). PG81действительно разработчиков сложно заставить ее постоянно заполнять. Особенно когда зменения незанчительные. Да,трудно. И в этом - одна из проблем документирования. А незначительные изменения имеют свойство накапливаться и постепенно превращаться в проблему. О крупных изменениях многие слышали и знают про них, а в чем заключвлись мелкие изменения и кто их делал - след теряется. Повторяю еще раз: необходимость во всех этих работах полностью зависит от того, как долго планируется использовать АИС и как часто необходимо вносить в неё изменения. А это все индивидуально. ... |
|||
:
Нравится:
Не нравится:
|
|||
03.02.2012, 16:09 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
DPH3по матрице Коуберна это шутка или поделитесь аналитикой на критерий? ... |
|||
:
Нравится:
Не нравится:
|
|||
04.02.2012, 22:05 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
Petro123DPH3по матрице Коуберна это шутка или поделитесь аналитикой на критерий? Э, не понял, а в чем проблемы с пользованием матрицей? Размер команды обычно известен, риски для потребителей также несложно прикинуть. А уж что конкретные решения зависят таки от конкретного проекта - достаточно очевидно. Ну нет смысла для проекта в D100 использовать тяжелые методологии и ГОСТы, созданные для проектов уровня D10000 или L100. ... |
|||
:
Нравится:
Не нравится:
|
|||
04.02.2012, 23:40 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
DPH3в чем проблемы с пользованием матрицей? :) дык кроме вас её тут никто не пользует. Или никто не пишет про использование. Дайте поиск. Есть ссылка на использование на доступном языке? ... |
|||
:
Нравится:
Не нравится:
|
|||
05.02.2012, 10:02 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
Petro123Есть ссылка на использование на доступном языке? Ну, само описание подхода - в статье http://www.maxkir.com/sd/methyperproject_RUS.htm Я, похоже, излишне оптимистично, думал, что это такой же must read, как и Брукс или ДиМарко - вот и ссылаюсь. Но тут посмотрел в яндексе - и, похоже, действительно, почти никто кроме меня не ссылается. А многие холивары в рамках этого подхода просто теряют смысл :) Вообще, если есть другой вариант описания размера и сложности проекта - то я с удовольствием прочитаю. Но как-то ничего не встречал... ... |
|||
:
Нравится:
Не нравится:
|
|||
06.02.2012, 00:25 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
PG81DPH3, Может документацию разбить на разделы (например html страницы) и каждый раздел так же как и программные модули вести в TFS (аналог CVS) По идее, документация будет состоять как из автоматически созданных частей, так и из документов, написанных разработчиками. В будущем - еще и постановки. По моему опыту, лучше wiki-систем ничего не придумано. Там, кстати, и встроенная система версий есть и многое другое. Начинать стоит прямо оттуда. Потом, например, можно добавить и автогенерацию документации по коммиту в TFS (надеюсь, там можно делать такое) - и тоже добавлять в wiki. Делать все в TFS - не очень хорошо, учить не программистов работать с TFS - не слишком просто, а при развитии документации это потребуется. Да, еще, из мелких советов: кроме обзора архитектуры очень советую завести документ "грязные хаки", где записывать все то, что пришлось делать из-за спешки или ошибок или еще чего-нибудь. Откровенное признание своих ошибок и уменьшает их число и позволяет потом их потихоньку исправлять. Да и знание очень полезное. А вы в каком городе? ... |
|||
:
Нравится:
Не нравится:
|
|||
06.02.2012, 02:20 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
DPH3Вообще, если есть другой вариант описания размера и сложности проекта - то я с удовольствием прочитаю. Но как-то ничего не встречал...я тоже не встречал, поэтому спс. за ссылку - почитаю. ... |
|||
:
Нравится:
Не нравится:
|
|||
06.02.2012, 09:18 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
DPH3советую завести документ "грязные хаки", у программистов это "костыли" ... |
|||
:
Нравится:
Не нравится:
|
|||
06.02.2012, 09:20 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
Petro123DPH3советую завести документ "грязные хаки", у программистов это "костыли" Ну, в вики эту страницу обычно называю Smells :) ... |
|||
:
Нравится:
Не нравится:
|
|||
06.02.2012, 09:46 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
Petro123DPH3Вообще, если есть другой вариант описания размера и сложности проекта - то я с удовольствием прочитаю. Но как-то ничего не встречал...я тоже не встречал, поэтому спс. за ссылку - почитаю. Хм, как прочитаешь - скажи, стоит ли по этому поводу, например, какую-нибудь статью написать. А то я содержимым статьи активно пользуюсь (а там есть некоторые тонкости, которые становятся заметны при практике). Или оно, в общем, нафиг никому не нужно? ... |
|||
:
Нравится:
Не нравится:
|
|||
06.02.2012, 09:47 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
DPH3Petro123пропущено... я тоже не встречал, поэтому спс. за ссылку - почитаю. Хм, как прочитаешь - скажи, стоит ли по этому поводу, например, какую-нибудь статью написать. А то я содержимым статьи активно пользуюсь (а там есть некоторые тонкости, которые становятся заметны при практике). Или оно, в общем, нафиг никому не нужно? всем нужно - пиши. Просто оценить и формализовать ЭТО очень трудно. Я по прежнему считаю, что программирование - искусство, а архитектор - просто отсекает лишнее, как скульптор. PS попозже почитаю, тут напишу. ... |
|||
:
Нравится:
Не нравится:
|
|||
06.02.2012, 10:33 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
PG81Кто как ведет разработку АИС? (любопытен опыт реально работающего сопровождения) Я бы не стал отдельно выделять сопровождение. В нынешних условиях проще и правильнее считать, что все время жизни программы - одно длинное сопровождение. А как.. большой вопрос, что именно Вас интересует? PG81Как ведется документирование проектов? По мне, наилучшие результаты даёт сочетание двух практик: хорошее комментирование модулей (в том числе - заголовочные комментарии, описывающие что здесь делается, зачем, и какое место это занимает в общей архитектуре) и краткая документация в чём-то википодобном, описывающая основные принципы и ключевые моменты. Кроме этого, заметная часть информации неизбежно расползается по вторичным источникам - трекеру, почте, тестам итп - но я бы не назвал это правильным документированием, скорее "источниками, которыми не следует пользоваться". PG81Как поддерживается эта документация в актуальном состоянии? Комментарии модифицируются вместе с кодом, а практика code review позволяет видеть недокомментированное и соответственно исправлять. Отдельная же документация в силу конструкции - краткое описание основ - редко нуждается в изменениях. PG81Отвечает ли за это специальные люди или отдел или разработчики самостоятельно поддерживают актуальность? Документацию для разработчиков не может поддерживать никто кроме разработчиков. Если ведётся пользовательская документация - в хорошем случае соответствующие этапы просто включены в workflow трекера. То есть задача после аналитика, разработчика и тестировщика попадает к техпису. Но чаще, к сожалению, "всякая байда которую надо написать по договору и стандартам" пишется совершенно отдельно от процесса разработки и с соответствующим качеством. PG81Имет ли вообще смысл вести системную документацию или может вообще разработку программ нужно вести определенным образом? Факт в том, что чем качественнее делается разработка - тем меньше документации требуется. ... |
|||
:
Нравится:
Не нравится:
|
|||
06.02.2012, 12:38 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
DPH3Для SQL я бы попробовал сделать генератор документации в вики-стиле (пакеты, таблицы, хранимки с комментариями специфического вида автоматически преобразовывать в вики-странички). Делов - не много, а пользы - дофига. Пользы ноль, вернее сказать. ... |
|||
:
Нравится:
Не нравится:
|
|||
06.02.2012, 12:42 |
|
Документирование разработок, поддержание актуальности
|
|||
---|---|---|---|
#18+
Ребят, вы чего? Что за бред тут понаписали в двадцати постах? Какая документация исходного кода? Какие вики по коду? Достаточно одного документика - так называемый "курс молодого бойца" с кратким введением что и как + документируется все внешнее api, протоколы и форматы передачи, торчащие из системы. Ну и, естественно, должна быть налажена система контроля версий (svn, git желательно), в которой хранится все - код, скрипты, документация + продвинутый багтрекер с возможностью project management (ну или хотя бы просто багтрекер). ... |
|||
:
Нравится:
Не нравится:
|
|||
06.02.2012, 12:46 |
|
|
start [/forum/topic.php?fid=33&msg=37645596&tid=1547880]: |
0ms |
get settings: |
10ms |
get forum list: |
15ms |
check forum access: |
4ms |
check topic access: |
4ms |
track hit: |
42ms |
get topic data: |
11ms |
get forum data: |
3ms |
get page messages: |
55ms |
get tp. blocked users: |
1ms |
others: | 299ms |
total: | 444ms |
0 / 0 |