"И всё равно, посреди всей этой тьмы, я вижу людей, которые не ломаются, я вижу людей, которые не сдаются. Даже зная, что надежда утрачена. И понимают, что от утраты до обретения, на самом деле, всего один шаг…"

В одной из статей на хабре наткнулся на спор о необходимости документации в принципе (бум!).

"Там документацию будете переписывать по 10 раз в день и в конце забьёте на неё"

"Для вхождения в проект нужно читать не доку, а код. Изучать библиотеки и общаться с другими программистами. А документация это максимум для справки, а не погружения."

Дожили.. Так вот господа/товарищи Хабровчане, со всей ответственностью заявляю, что с этой темнотой в умах будем бороться! Документация нужна, должна быть, поддерживаться и сопровождаться. Дальнейшее обсуждение будет направлено на раскрытие темы организации эффективной работы с документацией. Сами подходы и методологии не претендуют на номинацию "серебряной пули" и с полной открытостью оставляют за читателями право предложить свои подходы или развитию предложенных.

Документация программного обеспечения (ПО) — это совокупность всех письменных материалов, которые сопровождают программное обеспечение в процессе его разработки, тестирования, эксплуатации и сопровождения. Документация включает в себя требования, технические спецификации, руководства пользователя, инструкции по установке и эксплуатации, а также другие документы, необходимые для понимания и работы с программным обеспечением.

Документация программного обеспечения включает информацию, созданную для поддержки процесса разработки и эксплуатации системы или программного обеспечения, включая описание функций, данных, архитектуры и требований к ПО.

Виды документации

Документация программного обеспечения включает в себя несколько ключевых видов, которые можно разделить на технические и нетехнические категории:

Техническая документация:

1. Требования (Requirements Documentation):

   • Описание функциональных и нефункциональных требований к программному обеспечению. Включает в себя спецификации, бизнес-требования, пользовательские истории и другие артефакты, описывающие, что должно быть реализовано.

2. Архитектурная документация (Architecture Documentation):

   • Описание общей структуры программного обеспечения, включая схемы архитектуры, дизайн систем, описания модулей и их взаимодействие.

3. Дизайн-документация (Design Documentation):

   • Подробные описания внутреннего устройства и алгоритмов, используемых в программном обеспечении, включая диаграммы классов, ER-диаграммы, описания алгоритмов и другие технические чертежи.

4. Кодовая документация (Code Documentation):

   • Комментарии внутри кода, авто-документация, и дополнительные файлы, которые объясняют, как работает код. Это включает в себя также руководства по стилю кодирования и описания API.

5. Тестовая документация (Test Documentation):

   • Включает тестовые планы, тест-кейсы, отчеты о тестировании и автоматизированные тесты, которые обеспечивают проверку функциональности ПО.

6. Руководства пользователя (User Documentation):

   • Инструкции и справочные материалы, предназначенные для конечных пользователей ПО, включая руководства по эксплуатации, справки, FAQs и обучающие материалы.

Нетехническая документация:

1. Организационная документация (Organizational Documentation):

   • Описания организационных процессов, процедур и политик, таких как стандарты разработки, процессы управления проектами и процедуры контроля качества.

2. Методологическая документация (Methodological Documentation):

   • Описание методологий разработки и подходов, применяемых в проекте, таких как Agile, Scrum, Kanban и другие. Включает в себя руководство по использованию этих методологий в рамках конкретной организации или проекта.

3. Проектная документация (Project Documentation):

   • Включает в себя планы проектов, графики выполнения работ, отчеты о ходе выполнения и другие документы, относящиеся к управлению и контролю за проектом.

4. Юридическая документация (Legal Documentation):

   • Лицензионные соглашения, соглашения об уровне обслуживания (SLA), договора и другие юридические документы, связанные с программным обеспечением и его использованием.

Эти виды документации помогают обеспечить полноту и точность информации на всех этапах жизненного цикла программного обеспечения, от его разработки до эксплуатации и поддержки.

Какой документация должна быть?

Документация программного обеспечения (ПО) должна соответствовать следующим основным критериям:

1. Актуальность:

   • Документация должна быть обновлена в соответствии с последними изменениями в ПО. Это включает в себя обновление после каждой итерации разработки или изменения в коде.

2. Точность:

   • Документация должна точно, на должном уровне абстракции, отражать функциональность, архитектуру, интерфейсы и требования к программному обеспечению. Любые описания должны соответствовать реальной реализации ПО.

3. Понятность:

   • Информация должна быть представлена ясно и доступно для целевой аудитории. Это означает использование соответствующего уровня технических терминов и пояснений.

4. Полнота:

   • Документация должна охватывать все аспекты программного обеспечения, включая функциональные требования, архитектурные решения, инструкции по установке и эксплуатации, а также возможные ошибки и способы их устранения.

5. Доступность:

   • Документация должна быть легкодоступной для всех заинтересованных сторон, включая разработчиков, тестировщиков, пользователей и техническую поддержку. Это включает в себя удобство поиска и навигации по документам.

6. Стандартизация:

   • Документация должна соответствовать установленным стандартам и нормам, например таким как ISO/IEC/IEEE 12207 или внутренним стандартам компании. Это обеспечивает единообразие и совместимость документов.

7. Поддерживаемость:

   • Документация должна легко поддерживаться и обновляться в процессе жизненного цикла программного обеспечения. Структура и формат документации должны способствовать легкости внесения изменений.

Эти критерии помогают обеспечить, что документация будет полезной и эффективной на всех этапах жизненного цикла ПО, от разработки до поддержки и эксплуатации.

На этом разделе все те кто не понимал что такое документация и зачем она требуется надеюсь вопрос закрыли. Перейдем к вопросу "Кто ее поддерживает?".

Кто поддерживает документацию?

Самая простая и короткая формулировка ответа на этот вопросу будет: "Все"

Другая крайность приведет нас к штату специальных должностей, таких как, Системный аналитик, Бизнес аналитик, Технический писатель, Compliance специалист, CTO/CIO и другие. Но, это не означает необходимость спешно идти открывать новые позиции в отделе кадров, конечно. Все эти специальные позиции могут быть распределены в виде ролей по штатному расписанию, при наличии достаточной компетенции и ресурса у этих людей. В конечном счете, решение за руководителем и в качестве компетенций у сотрудников, на которых возложена эта задача.

Теперь, когда мы разобрались, кто отвечает за документацию, рассмотрим, как организовать этот процесс эффективно.

Рекомендации по эффективной работе с документацией

Организация эффективной работы с документацией является ключевым аспектом успешного управления проектами и жизненным циклом ПО. Эффективное управление документацией способствует улучшению коммуникации внутри команды, повышению качества продуктов, а также снижению рисков, связанных с ошибками и недопониманием. Вот несколько принципов и рекомендаций для организации работы с документацией, каждый из которых эксперт по работе с документацией может раскрыть, как минимум, до отдельной статьи:

1. Централизованное хранение и управление документами

Рекомендуется использовать централизованное хранилище для всей документации, чтобы обеспечить легкий доступ и удобство использования. Это может быть система управления документацией (DMS), репозиторий на основе облачных технологий (например, Confluence, SharePoint) или специализированные инструменты для управления проектной документацией.

Преимущества: Все участники команды имеют доступ к актуальной информации, что снижает риск использования устаревших данных и улучшает координацию работы.

2. Версионность и контроль изменений

Используйте инструменты для отслеживания версий документов (например, Git, системы контроля версий для документации), что позволяет сохранять историю изменений и быстро возвращаться к предыдущим версиям при необходимости.

Преимущества: Обеспечение прозрачности изменений и возможность отслеживать эволюцию документации. Это особенно важно для технической документации, которая может часто изменяться по мере разработки ПО.

3. Стандартизация и шаблоны

Внедрите стандарты и шаблоны для всех видов документации (например, требования, тест-кейсы, отчеты о прогрессе). Это помогает поддерживать единообразие, облегчает восприятие и снижает вероятность ошибок.

Преимущества: Упрощение создания новой документации и обеспечение соответствия всем документам внутри проекта установленным стандартам.

4. Регулярное обновление и актуализация

Обеспечьте регулярное обновление документации, особенно в случае изменений в проекте или продукте. Это может быть частью спринтов в Agile, когда после каждой итерации документация пересматривается и обновляется.

Преимущества: Снижение риска использования устаревшей информации, поддержание актуальности данных для всех участников проекта.

5. Доступность и понятность документации

Постарайтесь сделать документацию понятной и доступной для всех участников команды, вне зависимости от их уровня технической подготовки. Это включает в себя использование простого языка, визуальных материалов (схем, диаграмм) и разделение документации по уровням сложности.

Преимущества: Улучшение коммуникации и понимания между разными участниками команды, снижение риска ошибок из-за неправильного понимания документации.

6. Обратная связь и корректировка

Включите процесс сбора обратной связи от пользователей документации. Это может быть частью ретроспектив в Agile или регулярных встреч команды, где обсуждается, что работает хорошо, а что требует улучшений.

Преимущества: Постоянное улучшение качества документации и её соответствие реальным потребностям пользователей.

7. Обучение и поддержка

Организуйте обучение для команды по эффективному использованию и созданию документации. Это может включать воркшопы, семинары или внутренние курсы по использованию стандартов и инструментов документации.

Преимущества: Повышение квалификации команды, снижение времени на создание и использование документации, улучшение качества конечных документов.

8. Автоматизация работы с документацией

Используйте инструменты для автоматической генерации документации из кода или для интеграции документации с процессами CI/CD.

Преимущества: Снижение ручного труда, повышение точности и актуальности технической документации.

Эти принципы помогают организовать процесс работы с документацией таким образом, чтобы она не становилась бременем для команды, а наоборот, служила мощным инструментом для улучшения коммуникации, качества и скорости разработки программного обеспечения.

Заключение

Документация в ИТ - это не просто обязательная формальность, а важный инструмент, который помогает команде сохранять фокус, качество и скорость разработки. Она служит связующим звеном между всеми участниками процесса, обеспечивая понимание и согласованность на всех этапах проекта. Успешная работа с документацией требует не только создания, но и постоянного поддержания её актуальности и доступности. Организация эффективной работы с документацией — это не разовая задача, а непрерывный процесс, требующий внимания и дисциплины.

Поддержание документации на высоком уровне — залог успешного управления проектом и обеспечения его качественного выполнения. Пусть документация станет вашим надежным помощником, а не обузой. Применяя приведенные принципы и подходы, вы сможете наладить работу с документацией так, чтобы она приносила реальную пользу всей команде и проекту в целом.