Документирование результатов внутренней разработки. Стоит ли рисковать?

Я думаю, что каждый хоть раз встречался с результатами внедрения внутренней разработки в компании. Это может быть и крупная самописная система и маленькое приложение для преобразования из одного формата в другой. Документирование таких разработок ИТ специалистами и разработчиками редко ведется в достаточном объеме и качестве. И это не только "злой умысел" разработчика написать систему, в которой разбирается только он (по понятным причинам), и не количество задач которыми его "завалило" начальство и пользователи. Зачастую это нежелание "творца" тратить время на написание "ненужной" бумажки. Тем более, что после написания документации, её необходимо регулярно обновлять вместе с доработками и изменениями системы. К чему приводит такая политика и какие риски она несет для предприятия? Первый риск - при увольнении команды разработки (разработчики частенько уходят в стартапы или их перекупают софтверные компании) развитие системы приостанавливается, а иногда систему приходится заменять. Это конечно крайний случай, но и его нужно иметь ввиду, планируя собственную разработку. В лучшем случае нанимаются новые разработчики и они в течении N месяцев разбираются с исходным кодом. Время зависит и от качества исходного кода и скорости найма новых сотрудников. При этом необходимо учитывать, что разработчики не очень любят копаться в чужом коде. При менее критичной ситуации из команды уходит тимлид или один из разработчиков. В этом случае разработка новой функциональности не прекращается, но существенно замедляется. Конечно вы можете возразить, что при увольнении необходимо потребовать от сотрудников описания их проектов и документацию на систему. И вы даже ее получите, но за две недели описать результаты 2-3 х лет работы, и не забыть при этом мелочи, на мой взгляд не возможно. Еще один риск - это отпуск или больничный разработчика. Если в его отсутствие система ломается и отсутствует документация, остальные участники проекта испытывают совершенно не нужную дополнительную нагрузку и стресс, пытаясь в сжатые сроки разобраться в коде и исправить ошибку или восстановить работоспособность системы после сбоя. Конечно документирование это не панацея, но при качественном документировании как части рабочего процесса компания снижает свои риски, сроки восстановления системы и время на адаптацию новых сотрудников. Мой опыт в этом вопросе: Используйте вики, желательно на простом и удобном движке. Добавление и оформление статьи не должно занимать много времени. Например, Sharepoint 2010 с его вики мы использовать не смогли - слишком сложный процесс добавления и редактирования. На первой странице зафиксируйте правила оформления исходного кода и документирования результатов работы. Очень удобно когда репозиторий и вики интегрированы с системой постановки задач (багтрекинга). Если интеграции нет, то договоритесь о том, что бы в каждой статье и каждом комите по задаче была ссылка на эту самую задачу. Заранее продумайте области видимости для сотрудников компании - в вики вы можете положить не только внутреннюю документацию ИТ, но и инструкции пользователей и справочную информацию. Вики поддерживает загрузку документов, но если у вас есть портал или иное хранилище для проектной документации правильнее складывать ТЗ и требования, а также мануалы и описания в папку по проекту. Ссылку на эту папку указывать в вики. Оформление результатов разработки по разделам (понятно должно быть любому сотруднику ИТ, не только программисту): 1. Что это? При описании достаточно одного абзаца. 2. Описание установки. Как поставить и где развернуто. Желательно пошаговая инструкция. 3. Подробное описание логики работы и интеграций. 4. Администрирование. (Как добавить шаблон/отчет/пользователя и т.п.) 5. Работа над ошибками. (В ходе эксплуатации выявляются типовые проблемы - в этом разделе необходимо описать как они решаются). 6. Где лежит исходный код. 7. Доработки. Не все разделы нужны для каждого проекта. Полнота документирования сугубо индивидуально, но я сторонник инструкций для тупых, это в значительной степени сокращает время затрачиваемое новым сотрудником на взятие системы на сопровождение. Надеюсь, эта статья поможет организовать или хотя бы задуматься о документировании проектов в вашей компании.

Новая публикация

Долгое время я не публиковал новых статей по технологиям, и забросил свой блог. Отчасти это было связано с тем, что я практически перестал разрабатывать и все больше занимался архитектурой и управлением разработкой. Времени на вдумчивые статьи не хватало, а про ерунду писать не хотелось. Сегодня совершенно случайно посмотрел на свое детище и увидел, что кто-то заходит и смотрит мои старые статьи. Посмотрев на это я решил опубликовать пару статей на темы которыми занимался. Возможно они помогут начинающим и не очень ИТ специалистам решить свои задачи. В своих статьях я хочу затронуть следующие темы: Автоматизация предприятия. Старая тема - нужен ли внутренний портал предприятию и что полезного, на мой взгляд, он должен делать. Личный кабинет. Управление разработкой. Если у читателей есть интерес к какой-то из тем в большей степени, пишите в комментариях, буду на них ориентироваться.