Документации быть
Легион
»И всё равно, посреди всей этой тьмы, я вижу людей, которые не ломаются, я вижу людей, которые не сдаются. Даже зная, что надежда утрачена. И понимают, что от утраты до обретения, на самом деле, всего один шаг…»
В одной из статей на хабре наткнулся на спор о необходимости документации в принципе (бум!).
«Там документацию будете переписывать по 10 раз в день и в конце забьёте на неё»
«Для вхождения в проект нужно читать не доку, а код. Изучать библиотеки и общаться с другими программистами. А документация это максимум для справки, а не погружения.»
Дожили. Так вот господа/товарищи Хабровчане, со всей ответственностью заявляю, что с этой темностью в умах будем бороться! Документация нужна, должна быть, поддерживаться и сопровождаться. Дальнейшее обсуждение будет направлено на раскрытие темы организации эффективной работы с документацией. Сами подходы и методологии не претендуют на номинацию «серебряной пули» и с полной открытостью оставляют за читателями право предложить свои подходы или развитию предложенных.
Документация программного обеспечения (ПО) — это совокупность всех письменных материалов, которые сопровождают программное обеспечение в процессе его разработки, тестирования, эксплуатации и сопровождения. Документация включает в себя требования, технические спецификации, руководства пользователя, инструкции по установке и эксплуатации, а также другие документы, необходимые для понимания и работы с программным обеспечением.
Документация программного обеспечения включает информацию, созданную для поддержки процесса разработки и эксплуатации системы или программного обеспечения, включая описание функций, данных, архитектуры и требований к ПО.
Виды документации
Документация программного обеспечения включает в себя несколько ключевых видов, которые можно разделить на технические и нетехнические категории:
Техническая документация:
Требования (Requirements Documentation):
Описание функциональных и нефункциональных требований к программному обеспечению. Включает в себя спецификации, бизнес-требования, пользовательские истории и другие артефакты, описывающие, что должно быть реализовано.
Архитектурная документация (Architecture Documentation):
Описание общей структуры программного обеспечения, включая схемы архитектуры, дизайн систем, описания модулей и их взаимодействие.
Дизайн-документация (Design Documentation):
Подробные описания внутреннего устройства и алгоритмов, используемых в программном обеспечении, включая диаграммы классов, ER-диаграммы, описания алгоритмов и другие технические чертежи.
Кодовая документация (Code Documentation):
Комментарии внутри кода, авто-документация, и дополнительные файлы, которые объясняют, как работает код. Это включает в себя также руководства по стилю кодирования и описания API.
Тестовая документация (Test Documentation):
Включает тестовые планы, тест-кейсы, отчеты о тестировании и автоматизированные тесты, которые обеспечивают проверку функциональности ПО.
Руководства пользователя (User Documentation):
Инструкции и справочные материалы, предназначенные для конечных пользователей ПО, включая руководства по эксплуатации, справки, FAQs и обучающие материалы.
Нетехническая документация:
Организационная документация (Organizational Documentation):
Описания организационных процессов, процедур и политик, таких как стандарты разработки, процессы управления проектами и процедуры контроля качества.
Методологическая документация (Methodological Documentation):
Описание методологий разработки и подходов, применяемых в проекте, таких как Agile, Scrum, Kanban и другие. Включает в себя руководство по использованию этих методологий в рамках конкретной организации или проекта.
Проектная документация (Project Documentation):
Включает в себя планы проектов, графики выполнения работ, отчеты о ходе выполнения и другие документы, относящиеся к управлению и контролю за проектом.
Юридическая документация (Legal Documentation):
Лицензионные соглашения, соглашения об уровне обслуживания (SLA), договора и другие юридические документы, связанные с программным обеспечением и его использованием.
Эти виды документации помогают обеспечить полноту и точность информации на всех этапах жизненного цикла программного обеспечения, от его разработки до эксплуатации и поддержки.
Какой документация должна быть?
Документация программного обеспечения (ПО) должна соответствовать следующим основным критериям:
Актуальность:
Документация должна быть обновлена в соответствии с последними изменениями в ПО. Это включает в себя обновление после каждой итерации разработки или изменения в коде.
Точность:
Документация должна точно, на должном уровне абстракции, отражать функциональность, архитектуру, интерфейсы и требования к программному обеспечению. Любые описания должны соответствовать реальной реализации ПО.
Понятность:
Полнота:
Документация должна охватывать все аспекты программного обеспечения, включая функциональные требования, архитектурные решения, инструкции по установке и эксплуатации, а также возможные ошибки и способы их устранения.
Доступность:
Документация должна быть легкодоступной для всех заинтересованных сторон, включая разработчиков, тестировщиков, пользователей и техническую поддержку. Это включает в себя удобство поиска и навигации по документам.
Стандартизация:
Документация должна соответствовать установленным стандартам и нормам, например таким как ISO/IEC/IEEE 12207 или внутренним стандартам компании. Это обеспечивает единообразие и совместимость документов.
Поддерживаемость:
Документация должна легко поддерживаться и обновляться в процессе жизненного цикла программного обеспечения. Структура и формат документации должны способствовать легкости внесения изменений.
Эти критерии помогают обеспечить, что документация будет полезной и эффективной на всех этапах жизненного цикла ПО, от разработки до поддержки и эксплуатации.
На этом разделе все те кто не понимал что такое документация и зачем она требуется надеюсь вопрос закрыли. Перейдем к вопросу «Кто ее поддерживает?».
Кто поддерживает документацию?
Самая простая и короткая формулировка ответа на этот вопросу будет: «Все»
Другая крайность приведет нас к штату специальных должностей, таких как, Системный аналитик, Бизнес аналитик, Технический писатель, Legacy специалист, CTO/CIO и другие. Но, это не означает необходимость спешно идти открывать новые позиции в отделе кадров, конечно. Все эти специальные позиции могут быть распределены в виде ролей по штатному расписанию, при наличии достаточной компетенции и ресурса у этих людей. В конечном счете, решение за руководителем и в качестве компетенций у сотрудников, на которых возложена эта задача.
Теперь, когда мы разобрались, кто отвечает за документацию, рассмотрим, как организовать этот процесс эффективно.
Рекомендации по эффективной работе с документацией
Организация эффективной работы с документацией является ключевым аспектом успешного управления проектами и жизненным циклом ПО. Эффективное управление документацией способствует улучшению коммуникации внутри команды, повышению качества продуктов, а также снижению рисков, связанных с ошибками и недопониманием. Вот несколько принципов и рекомендаций для организации работы с документацией, каждый из которых эксперт по работе с документацией может раскрыть, как минимум, до отдельной статьи:
1. Централизованное хранение и управление документами
Рекомендуется использовать централизованное хранилище для всей документации, чтобы обеспечить легкий доступ и удобство использования. Это может быть система управления документацией (DMS), репозиторий на основе облачных технологий (например, Confluence, SharePoint) или специализированные инструменты для управления проектной документацией.
Преимущества: Все участники команды имеют доступ к актуальной информации, что снижает риск использования устаревших данных и улучшает координацию работы.
2. Версионность и контроль изменений
Используйте инструменты для отслеживания версий документов (например, Git, системы контроля версий для документации), что позволяет сохранять историю изменений и быстро возвращаться к предыдущим версиям при необходимости.
Преимущества: Обеспечение прозрачности изменений и возможность отслеживать эволюцию документации. Это особенно важно для технической документации, которая может часто изменяться по мере разработки ПО.
3. Стандартизация и шаблоны
Внедрите стандарты и шаблоны для всех видов документации (например, требования, тест-кейсы, отчеты о прогрессе). Это помогает поддерживать единообразие, облегчает восприятие и снижает вероятность ошибок.
Преимущества: Упрощение создания новой документации и обеспечение соответствия всем документам внутри проекта установленным стандартам.
4. Регулярное обновление и актуализация
Обеспечьте регулярное обновление документации, особенно в случае изменений в проекте или продукте. Это может быть частью спринтов в Agile, когда после каждой итерации документация пересматривается и обновляется.
Преимущества: Снижение риска использования устаревшей информации, поддержание актуальности данных для всех участников проекта.
5. Доступность и понятность документации
Постарайтесь сделать документацию понятной и доступной для всех участников команды, вне зависимости от их уровня технической подготовки. Это включает в себя использование простого языка, визуальных материалов (схем, диаграмм) и разделение документации по уровням сложности.
Преимущества: Улучшение коммуникации и понимания между разными участниками команды, снижение риска ошибок из-за неправильного понимания документации.
6. Обратная связь и корректировка
Включите процесс сбора обратной связи от пользователей документации. Это может быть частью ретроспектив в Agile или регулярных встреч команды, где обсуждается, что работает хорошо, а что требует улучшений.
Преимущества: Постоянное улучшение качества документации и её соответствие реальным потребностям пользователей.
7. Обучение и поддержка
Организуйте обучение для команды по эффективному использованию и созданию документации. Это может включать воркшопы, семинары или внутренние курсы по использованию стандартов и инструментов документации.
Преимущества: Повышение квалификации команды, снижение времени на создание и использование документации, улучшение качества конечных документов.
8. Автоматизация работы с документацией
Используйте инструменты для автоматической генерации документации из кода или для интеграции документации с процессами CI/CD.
Преимущества: Снижение ручного труда, повышение точности и актуальности технической документации.
Эти принципы помогают организовать процесс работы с документацией таким образом, чтобы она не становилась бременем для команды, а наоборот, служила мощным инструментом для улучшения коммуникации, качества и скорости разработки программного обеспечения.
Заключение
Документация в ИТ — это не просто обязательная формальность, а важный инструмент, который помогает команде сохранять фокус, качество и скорость разработки. Она служит связующим звеном между всеми участниками процесса, обеспечивая понимание и согласованность на всех этапах проекта. Успешная работа с документацией требует не только создания, но и постоянного поддержания её актуальности и доступности. Организация эффективной работы с документацией — это не разовая задача, а непрерывный процесс, требующий внимания и дисциплины.
Поддержание документации на высоком уровне — залог успешного управления проектом и обеспечения его качественного выполнения. Пусть документация станет вашим надежным помощником, а не обузой. Применяя приведенные принципы и подходы, вы сможете наладить работу с документацией так, чтобы она приносила реальную пользу всей команде и проекту в целом.
