Embed Size (px)
Citation preview
Документирование долгоживущих веб-проектов
Глеб БелогорцевРосБизнесКонсалтинг
ВведениеИдеальная документация – всеобъемлющая документация?
• На создание требуется вечность• Нужно поддерживать актуальность• Реально используется только малая часть
ВведениеА может, ну её? Главное – код?
• Нужно минимизировать потерю знаний
• А еще лучше – обеспечить их рост
ВведениеДисклеймер• документация для разработчиков• пишется силами разработчиков• время ограниченоНо выводы делаются на основе общих принципов.
Определение целейЗачем вообще нужна документация?
Какие могут быть цели?
Определение целей• Иметь под рукой базовую информацию о проекте (входы, выходы,
интерфейсы)
• Облегчить погружение в проект новых сотрудников
• Стандартизировать регулярно возникающие задачи по поддержке, распространить знания о них
• Сохранить знания по технически сложным и неочевидным деталям реализации
• Отслеживать изменения на проекте
Определение набора артефактовКритерии выбора• Соответствие выбранным целям• Простота создания и поддержания
актуальности
Определение набора артефактов
Затраты на создание артефакта должны покрываться экономией времени от его
использования
Определение набора артефактовПример: диаграмма последовательности
Описывает процесс, в котором легко разобраться по коду, или который часто меняется – не нужна.
Описывает очень сложный процесс или вы умеете генерировать её автоматически – нужна.
Варианты артефактовТребования:
• Функциональные
• Надежность
• Производительность
• Возможность поддержки
• …
Варианты артефактов
Описание архитектуры
Текстовое Диаграммы Предварительное
Варианты артефактовОписание организационных вопросов
• Кто за что отвечает
• Адреса, телефоны
• Регламенты
Варианты артефактовHOWTO («Как это сделать»)
Сделать А Сделать Б Проверить В Profit!
Варианты артефактовКомментарии в коде
• Должны быть по умолчанию
• Из них можно генерить документацию (см. phpDocumentor). А можно не генерить.
Варианты артефактовЛог изменений на проекте
Варианты:- Выборка из баг-трекера- svn log- Лог внедрений
Определение набора артефактов
Мы набросали ряд целей. Какие артефакты подходят в каждом случае?
Мой выборКарточка проекта – сводная информация о нем
• Название
• URL SVN
• URL проекта
• URL админки
• закрытые разделы (и как получать доступ)
• платформа (язык, фреймворк)
• ...
Мой выборВходы (какими путями на проект попадают данные: где добавляются пользователями, откуда и как импортируются)
Выходы (какими путями данные отдаются проектом)
Управление (как он управляется: админка, сигналы с других проектов)
Список разделов (в т. ч. функциональное описание разделов сайта)
HOWTO (описание решения типовых задач)
Лог изменений
ИнструментыТребования к хранилищу документации:
• Удобное редактирование
• Поиск
• Гиперссылки
• Аттачи
• Версионность
• Возможность задавать структуру дерева документов и работать с ней
Инструменты
Как хранить документы?
Wiki Plain text+SVN
ИнструментыWikiМного функций «из коробки».Нет жесткой структуры, работы с деревьями документов.
ИнструментыPlain text + SVN (asciidoc, Doxygen, LaTeX)
Можно управлять структурой и представлением.Дополнительные фичи нужно дописывать самостоятельно. Неудобно редактировать.
Инструменты• Mwdiawiki (+Sphinx search, breadcrumbs)
• Автогенерация комментариев к коммитам
PRJ – TASK#1234: Задача. Описание изменений.
• Письма о внедрении и лог изменений• phpDocumentor
Внедрение документирования
Внедрение
Первичное заполнение
Поддержание актуальности
Внедрение документированияПервичное заполнение:• Метод «съесть слона»• Распараллелить работу• Поручить новичкам• Пообещать плюшки
Внедрение документированияПоддержание актуальности• Нужен «библиотекарь»• Проверка на необходимость
документирования – после внедрения
Почитать по темеК. Ларман, «Применение UML 2.0 и шаблонов проектирования»
С. Макконнелл, «Совершенный код»
Т. Лимончелли, «Тайм-менеджмент для системных администраторов»
Фредерик Брукс, «Мифический человеко-месяц»
