14 типов документации по разработке программного обеспечения (плюс советы)

17 июня 2021 г.

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

Что такое документация для разработки программного обеспечения?

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

1. Планирование

2. Анализ

3. Дизайн

4. Реализация

5. Тестирование

6. Обслуживание

14 видов документации по разработке программного обеспечения

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

1. Технологическая документация

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

2. Планировочная документация

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

• Проблемы, которые программа решит

• Подход к разработке, который будет использовать команда

• Основные функции программного обеспечения

• Порядок разработки

• Лидерские роли в проекте

• Обязанности каждого члена команды

3. Сметная документация

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

4. Стандартная документация

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

5. Документация по метрикам

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

• Сравните разные методы разработки

• Подготовить спецификации качества

• Измеряйте точность оценок усилий

• Предоставляйте менеджерам обратную связь на протяжении всего процесса разработки

6. Планирование документации

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

7. Документация по продукту

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

8. Системная документация

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

• Возможности

• Дизайн

• Ограничения

• Операция

• Обслуживание

9. Документация по требованиям

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

10. Архитектурно-конструкторская документация

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

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

Техническая документация описывает, как программное обеспечение использует или строит существующие технологические концепции. Как следует из названия, он предназначен для специалистов по информационным технологиям (ИТ) и инженеров-программистов, которые используют его для обеспечения качественного взаимодействия с пользователем и завоевания доверия и лояльности клиентов. Техническая документация включает такие элементы, как маршруты интерфейса прикладного протокола (API), которые позволяют программному обеспечению взаимодействовать с устройством пользователя, а также комплекты разработки программного обеспечения (SDK) или набор инструментов, используемых разработчиками для создания программного обеспечения.

12. Пользовательская документация

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

13. Документация для конечного пользователя

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

• Требования к операционной системе

• Инструкции по установке

• Как запустить и использовать программу

• Фотографии функций программного обеспечения

• Советы по устранению неполадок

• Контактная информация службы поддержки клиентов

14. Документация системного администратора

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

Советы по документации по разработке программного обеспечения

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

Включите файл README перед подробностями кодирования

Файлы README — это основные текстовые документы, которые описывают программное обеспечение для пользователей и программистов. Они могут помочь конечным пользователям и системным администраторам в использовании продукта, а также предоставить новым членам группы разработчиков обзор проекта. Файлы README могут включать:

• Инструкции по настройке, установке и эксплуатации

• Список включенных файлов

• Лицензионная информация

• Известные ошибки

• Кредиты

Создайте трекер проблем для сбора отзывов

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

Включите соглашения о кодировании в техническую документацию

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

• Практики

• Принципы

• Организация

• Отступ

• Комментарии

• Соглашения об именах

• Заявления

• Декларации

Перечислите все версии ваших файлов с изменениями, которые вы внесли в каждую из них.

Лучше всего указать каждую версию созданных вами файлов и все изменения, которые вы в них внесли, в документации по разработке программного обеспечения. Некоторые разработчики предпочитают использовать программное обеспечение для управления версиями, в то время как другие просто добавляют суффикс в конец файлов вручную, например v2, v3 или v4. Другие ключевые термины, такие как «черновик», «окончательный» или «обрезанный», также сообщают вашим коллегам, какие версии файлов ваша команда обновляла в последнее время.

Добавьте свой адрес электронной почты в конце документации

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