Разработка документации для приложения

Разработка документации для приложения — это создание описания программы для пользователей и разработчиков. Техническая документация объясняет, как устроено ПО и как с ним работать. В статье разобраны виды документации, состав программной документации и инструменты для её создания.

Содержание

Материал разбит на смысловые блоки. Каждый пункт отвечает на конкретный вопрос.

•     Что такое техническая документация
•     Что такое документация приложений
•     Зачем нужна техническая документация
•     Виды технической документации
•     Состав программной документации
•     Какие основные разделы должна включать документация
•     Руководство пользователя
•     Руководство программиста и его структура
•     Проектный документ программного обеспечения
•     Как писать документацию
•     Документация как код
•     Инструменты для создания документации
•     Стандарты и ГОСТ
•     Что требуется от заказчика для подготовки документов на ПО
•     Как читать техническую документацию
•     Ошибки при разработке документации

Дальше каждый пункт разобран по порядку. Материалы помогут выстроить работы с документами.

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

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

Такое описание нужно и разработчиков, и конечных пользователей. Без него знания живут только в головах команды проекта.

•     как устроено программного обеспечения
•     какие функции есть у программы
•     как идёт обмен данных между модулями программы
•     что делать при ошибке

Это рабочий инструмент разработки, а не формальность.

Что такое документация приложений

Документация приложений — частный случай технической документации. Она описывает конкретное мобильное или веб-приложение.

Часть материалов пишут для пользователей, часть — для разработчиков. Состав зависит от целей проекта.

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

Для внутреннего сервиса документов меньше, чем для коробочного продукта.

Важно! Документация должна жить вместе с кодом. Устаревшее описание вредит сильнее, чем его отсутствие.

Зачем нужна техническая документация

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

Она же ускоряет поддержку и обучение. Компании это экономит ресурсы и повышает эффективность работы.

•     передать знания новым разработчикам
•     сократить обращения в поддержку
•     зафиксировать договорённости по проекту
•     упростить анализ и развитие системы

Документы окупаются на первой же смене команды.

Виды технической документации

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

Управленческие материалы фиксируют сроки и требования разработки. Обычно проекту нужны все виды сразу.

Объём каждого вида зависит от масштаба программы.

Состав программной документации

Состав программной документации задаётся стандартами и практикой разработки. Базовый набор одинаков для большинства проектов.

Разработка программной документации обычно даёт такие документы проекта:

•     техническое задание на систему
•     описание программы и её функций
•     руководство пользователя и программиста
•     программа и методика испытаний

Каждый документ решает свою задачу, дублировать содержание не нужно.

Какие основные разделы должна включать документация

Структура почти всегда повторяется. Это упрощает поиск информации.

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

•     назначение и область применения
•     требования к системе и оборудованию
•     описание функций и интерфейсов
•     порядок установки и настройки
•     типовые ошибки и их решение

Такой каркас подходит и мобильному, и веб-продукту.

Руководство пользователя

Руководство пользователя объясняет работу с программой простым языком. Его читают люди без технических знаний.

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

•     краткое описание возможностей программы
•     пошаговые инструкции по основным задачам
•     ответы на вопросы в формате FAQ
•     контакты поддержки

Такой документ удобно отдавать в PDF или HTML: его можно скачать или читать онлайн.

Руководство программиста и его структура

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

В нём описывают модули, форматы данных и примеры вызовов API.

1.       Назначение и условия применения программы.
2.       Требования к системе и среде.
3.       Обращение к программе и её интерфейсам.
4.       Входные и выходные данные.
5.       Сообщения об ошибках.

Уместны фрагменты кода на Java или другом языке разработки.

Проектный документ программного обеспечения

Проектный документ фиксирует замысел системы до начала разработки. Это звено между техническим заданием и кодом.

В нём описывают архитектуру, ключевые решения и ограничения. На его основе оценивают сроки и ресурсы.

•     согласовать подход к разработке
•     зафиксировать варианты решений
•     оценить эффективность схемы
•     избежать переделок в середине проекта

По нему же потом проверяют результат работы.

Как писать документацию

Писать документацию стоит короткими блоками. Длинный текст без структуры никто не читает.

Начинают с ответа на вопрос «зачем это нужно», дальше дают порядок действия.

1.       Определить, для кого пишется документ.
2.       Составить структуру разделов.
3.       Описать сценарии по шагам.
4.       Проверить текст на реальном пользователе.

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

Документация как код

Подход Docs as Code хранит документацию рядом с исходный код в Git. Правки проходят ревью так же, как изменения в программе.

Версии документов совпадают с версиями продукта, публикация идёт автоматически.

•     описание не отстаёт от кода
•     история изменений в одном месте
•     проверка встроена в процесс разработки
•     публикация в HTML или PDF настраивается один раз

Docs as Code стал стандартом в IT-командах с частыми релизами.

Инструменты для создания документации

Инструмент выбирают под формат и команду. Простому проекту хватает текстового редактора.

Описание API часто собирают автоматически из кода. Отдельные сервисы дают базу знаний с поиском.

•     Markdown и генераторы документации
•     автогенерация описания API
•     базы знаний и вики компании
•     редакторы с экспортом в PDF

Часть задач сегодня закрывает ИИ: он помогает получить черновик и вычитать текст.

Стандарты и ГОСТ

В России состав документов часто задают стандарты. Для государственных проектов ГОСТ обязателен.

Стандарты описывают структура и оформление, задают список обязательных разделов.

•     единый формат материалов в компании
•     прохождение приёмки и аудита
•     меньше споров с заказчиком
•     понятная логика для новых сотрудников

Слепо следовать стандарту не нужно: текст должен быть полезен читателю.

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

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

Нужны описание процессов, доступ к системе и контакты специалистов. Отдельно согласуют формат и сроки.

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

Чем полнее исходные данные, тем быстрее идёт разработка.

Как читать техническую документацию

Документацию читают не подряд, а по задаче. Сначала смотрят оглавление и назначение программы.

1.       Просмотреть структуру и разделы.
2.       Найти раздел под свою задачу.
3.       Разобрать пример и повторить его.
4.       Проверить ограничения и ошибки.

Такой порядок экономит времени: не нужно изучать всё руководство ради одной операции.

Ошибки при разработке документации

Ошибки в разработке документации повторяются из проекта в проект. Часто её пишут для галочки и не обновляют.

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

•     документация не обновляется после релиза
•     один документ закрывает все цели сразу
•     нет примеров и понятных инструкций
•     файлы с данными разбросаны по почте и чатам

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

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