![Page 1: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/1.jpg)
Документирование долгоживущих веб-проектов
Глеб БелогорцевРосБизнесКонсалтинг
![Page 2: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/2.jpg)
ВведениеИдеальная документация – всеобъемлющая документация?
• На создание требуется вечность• Нужно поддерживать актуальность• Реально используется только малая часть
![Page 3: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/3.jpg)
ВведениеА может, ну её? Главное – код?
• Нужно минимизировать потерю знаний
• А еще лучше – обеспечить их рост
![Page 4: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/4.jpg)
ВведениеДисклеймер• документация для разработчиков• пишется силами разработчиков• время ограниченоНо выводы делаются на основе общих принципов.
![Page 5: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/5.jpg)
Определение целейЗачем вообще нужна документация?
Какие могут быть цели?
![Page 6: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/6.jpg)
Определение целей• Иметь под рукой базовую информацию о проекте (входы, выходы,
интерфейсы)
• Облегчить погружение в проект новых сотрудников
• Стандартизировать регулярно возникающие задачи по поддержке, распространить знания о них
• Сохранить знания по технически сложным и неочевидным деталям реализации
• Отслеживать изменения на проекте
![Page 7: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/7.jpg)
Определение набора артефактовКритерии выбора• Соответствие выбранным целям• Простота создания и поддержания
актуальности
![Page 8: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/8.jpg)
Определение набора артефактов
Затраты на создание артефакта должны покрываться экономией времени от его
использования
![Page 9: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/9.jpg)
Определение набора артефактовПример: диаграмма последовательности
Описывает процесс, в котором легко разобраться по коду, или который часто меняется – не нужна.
Описывает очень сложный процесс или вы умеете генерировать её автоматически – нужна.
![Page 10: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/10.jpg)
Варианты артефактовТребования:
• Функциональные
• Надежность
• Производительность
• Возможность поддержки
• …
![Page 11: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/11.jpg)
Варианты артефактов
Описание архитектуры
Текстовое Диаграммы Предварительное
![Page 12: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/12.jpg)
Варианты артефактовОписание организационных вопросов
• Кто за что отвечает
• Адреса, телефоны
• Регламенты
![Page 13: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/13.jpg)
Варианты артефактовHOWTO («Как это сделать»)
Сделать А Сделать Б Проверить В Profit!
![Page 14: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/14.jpg)
Варианты артефактовКомментарии в коде
• Должны быть по умолчанию
• Из них можно генерить документацию (см. phpDocumentor). А можно не генерить.
![Page 15: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/15.jpg)
Варианты артефактовЛог изменений на проекте
Варианты:- Выборка из баг-трекера- svn log- Лог внедрений
![Page 16: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/16.jpg)
Определение набора артефактов
Мы набросали ряд целей. Какие артефакты подходят в каждом случае?
![Page 17: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/17.jpg)
Мой выборКарточка проекта – сводная информация о нем
• Название
• URL SVN
• URL проекта
• URL админки
• закрытые разделы (и как получать доступ)
• платформа (язык, фреймворк)
• ...
![Page 18: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/18.jpg)
Мой выборВходы (какими путями на проект попадают данные: где добавляются пользователями, откуда и как импортируются)
Выходы (какими путями данные отдаются проектом)
Управление (как он управляется: админка, сигналы с других проектов)
Список разделов (в т. ч. функциональное описание разделов сайта)
HOWTO (описание решения типовых задач)
Лог изменений
![Page 19: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/19.jpg)
ИнструментыТребования к хранилищу документации:
• Удобное редактирование
• Поиск
• Гиперссылки
• Аттачи
• Версионность
• Возможность задавать структуру дерева документов и работать с ней
![Page 20: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/20.jpg)
Инструменты
Как хранить документы?
Wiki Plain text+SVN
![Page 21: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/21.jpg)
ИнструментыWikiМного функций «из коробки».Нет жесткой структуры, работы с деревьями документов.
![Page 22: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/22.jpg)
ИнструментыPlain text + SVN (asciidoc, Doxygen, LaTeX)
Можно управлять структурой и представлением.Дополнительные фичи нужно дописывать самостоятельно. Неудобно редактировать.
![Page 23: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/23.jpg)
Инструменты• Mwdiawiki (+Sphinx search, breadcrumbs)
• Автогенерация комментариев к коммитам
PRJ – TASK#1234: Задача. Описание изменений.
• Письма о внедрении и лог изменений• phpDocumentor
![Page 24: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/24.jpg)
Внедрение документирования
Внедрение
Первичное заполнение
Поддержание актуальности
![Page 25: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/25.jpg)
Внедрение документированияПервичное заполнение:• Метод «съесть слона»• Распараллелить работу• Поручить новичкам• Пообещать плюшки
![Page 26: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/26.jpg)
Внедрение документированияПоддержание актуальности• Нужен «библиотекарь»• Проверка на необходимость
документирования – после внедрения
![Page 27: документирование долгоживущих веб проектов. г. белогорцев. зал 3](https://reader036.vdocuments.net/reader036/viewer/2022062405/557f9489d8b42a522c8b4bd9/html5/thumbnails/27.jpg)
Почитать по темеК. Ларман, «Применение UML 2.0 и шаблонов проектирования»
С. Макконнелл, «Совершенный код»
Т. Лимончелли, «Тайм-менеджмент для системных администраторов»
Фредерик Брукс, «Мифический человеко-месяц»