Документирование программных продуктов
Основная задача технического писателя – создавать понятную и структурированную документацию к программным продуктам. Это трудоемкий процесс, поэтому, чтобы облегчить себе жизнь, действую по алгоритму (см. Схему 1).
Процесс разработки
Схема 1. Процесс документирования ПО
Применяю общепринятый подход к документированию. Действую поэтапно:
- Анализирую задачу. Уточняю детали, декомпозирую задачу, оцениваю примерные сроки. Важно понимать:
- Что документирую. Какой программный продукт.
- Кто целевая аудитория продукта.
- Какие доступны источники информации: тестовый стенд, легаси документов, база знаний, комментарии в коде, специалисты.
- С какой целью создается документация. Кто, где и в каких обстоятельствах будет ей пользоваться.
- Какие документы требуется разработать (исчерпывающий перечень). В какой срок.
- Каким требованиям должны соответствовать документы (стайлгайдам, редакционной политике, нормативам).
- По каким критериям будет оцениваться результат.
- Собираю сведения о продукте. Создаю файловую структуру. Заполняю мастер-документ.
- Составляю документы. Подготавливаю схемы и иллюстрации. Пишу текст. Оформляю внешний вид и нужный формат. Проверяю результат.
- Отправляю документы на проверку (docs review). Устраняю замечания. Вношу исправления и дополнения.
- Закрываю задачу. Удаляю все лишнее. Заполняю Readme-файл. Архивирую.
Примеры документов
Обновлено