Мы часто сталкиваемся с отсутствием документации к продукту, программе или если она и есть, но настолько непонятная и не полная, что читать ее бесполезно.
Сегодня я постараюсь описать процесс создания вменяемой документации на созданный вами программный продукт. Документации для пользователя и для программистов, зацепим все аспекты. Букв будет много, тема большая.
План на документацию.
Для написания документации на продукт можно обратиться к стандартам, где на сегодня есть два типа:
- Международные стандарты (ISO, IEEE Std);
- Советские и Российские ГОСТы. (В обозначении Российских стандартов –
- всегда указан символ Р).
Список основных международных стандартов для написания документации:
- IEEE Std 1063-2001 «IEEE Standard for Software User Documentation» —
- стандарт для написания руководства пользователя;
- IEEE Std 1016-1998 «IEEE Recommended Practice for Software Design
- Descriptions» — стандарт для написания технического описания программы;
- ISO/IEC FDIS 18019:2004 «Guidelines for the design and preparation of user
- documentation for application software» — ещё один стандарт для написания
- руководства пользователя. Содержит большое количество примеров,
- похоже на руководство по написанию руководства пользователя.
- ISO/IEC 26514:2008 «Requirements for designers and developers of user
- documentation» — стандарт для дизайнеров и разработчиков
- пользователей документации.
Советские и Российские ГОСТы
ГОСТы — это нечто, что разрабатывалось при Советском Союзе, их слишком много. Мы говорим про ГОСТы для IT разработкой которых не так активно занимались наши ученые и поэтому их не так много, и они все не потеряли актуальности.
Для написания документации на программу используются две серии ГОСТов:
- ГОСТ 19 Единая система программной документации (ЕСПД)
- ГОСТ 34 Информационные технологии. Комплекс стандартов на автоматизированные системы.
Остановимся именно на Российских стандартах, так как если вы хотите попасти в реестр Российского ПО и стать аккредитованной ИТ компанией, вам нужно применять именно эти стандарты.
ГОСТ 19. ЕСПД
ЕСПД (единая система программной документации)
Комплекс государственных стандартов (ГОСТ), устанавливающих взаимосвязанные правила разработки, оформления и обращения программ и программной документации. Стандарты ЕСПД устанавливают требования, регламентирующие разработку, сопровождение, изготовление и эксплуатацию программ.
Определения применяемые в ЕСПД:
- Программа — данные, предназначенные для управления конкретными
- компонентами системы обработки информации в целях реализации определённого алгоритма.
- Программное обеспечение — совокупность программ системы обработки
- информации и программных документов, необходимых для эксплуатации этих программ.
Важно, при написании документации четко указывать на два этих определения и не путать при создании описания.
ГОСТ 34. ИТ
Разбираемся с ГОСТ 34, как основной для информационых технологий.
Определение из ГОСТ 34
- Автоматизированная система (АС) — система, состоящая из персонала и комплекса средств автоматизации его деятельности, реализующая информационную технологию выполнения установленных функций.
АС разделяются в зависимости от вида деятельности, например:
- автоматизированные системы управления (АСУ);
- системы автоматизированного проектирования (САПР);
- автоматизированные системы научных исследований (АСНИ) и другие.
ГОСТ 34 разделяет виды обеспечения АС:
- Организационное;
- Методическое;
- Техническое;
- Математическое;
- Программное обеспечение;
- Информационное;
- Лингвистическое;
- Правовое;
- Эргономическое.
Автоматизированная система — это не программа, а комплекс видов обеспечения, среди которых есть и программное обеспечение.
Автоматизированная система, как правило, содержит организационное решение под конкретного пользователя и заказчика, где программа может быть создана и растиражирована под большое количество пользователей без привязки к какому-либо предприятию.
Если разрабатывается документация на программу, которую создают под конкретное предприятие, то используется ГОСТ 34.
Если разрабатывается документация на массовую программу, то используется ГОСТ 19.
Создание технического задания.
Пункты для технического задания ГОСТа 34 и ГОСТа 19 отличаются, поэтому стоит их рассмотреть как отдельный раздел. Техническое задание - это важная часть программного продукта.
Состав ГОСТ 34 ИТ.
- ГОСТ 34.201-89 Виды, комплектность и обозначения документов при
- создании автоматизированных систем
- ГОСТ 34.320-96 Концепции и терминология для концептуальной схемы и
- информационной базы
- ГОСТ 34.321-96 Информационные технологии. Система стандартов по базам данных. Эталонная модель управления
- ГОСТ 34.601-90 Автоматизированные системы. Стадии создания
- ГОСТ 34.602-89 Техническое задание на создание автоматизированной
- системы
- ГОСТ 34.603-92 Информационная технология. Виды испытаний
- автоматизированных систем
- РД 50-34.698-90 Автоматизированные системы. Требования к содержанию
- документов
- ГОСТ Р ИСО/МЭК 8824-3-2002 Информационная технология. Абстрактная
- синтаксическая нотация версии один
- ГОСТ Р ИСО/МЭК 10746-3-2001 Управление данными и открытая
- распределённая обработка.
- ГОСТ Р ИСО/МЭК 15271-02 Процессы жизненного цикла программных
- средств
- ГОСТ Р ИСО/МЭК 15910-2002 Процесс создания документации пользователя программного средства
Применяя ГОСТ 34 ИТ, можно добиться хорошей структуры документа, читаемости не подготовленными специалистами, а так же получить качественный на выходе продукт.
Состав документации к программному проекту ПМИ
Часто компании задаются вопросом, а стоит ли делать все по ГОСТ, можно же просто применить рекомендации по составу документации и все.
Это тоже путь и тогда стоит учесть минимум, что при разработке АС и созданию документации нужно иметь:
- Техническое задание
- Руководство оператора
- Руководство программиста
- Руководство системного программиста
Если же идти по ГОСТ:
- Техническое задание
- Пояснительная записка
- Руководство оператора
- Программа и методика испытаний
- Опционально, при необходимости в требования к документации включаются:
- Описание языка
- Руководство программиста
- Руководство системного программиста
Подведем промежуточные итоги. Мы выяснили каким образом можно обеспечить целостность документации. Построить правильную структуру и всецело подготовить документ для чтения будущими пользователями. Выбирая путь не используя стандартов, можно получить очень печальную и не пригодную для работы документацию. Поддерживать ее актуальность будет физически не возможно, а без актуальных данных любая инструкция теряет свой смысл существования.
Средства обработки, создания документации
Теоретическая база, заложенная стандартами, — это скелет документации. Но чтобы оживить ее, наполнить содержанием и сделать удобной для использования, необходимы современные и эффективные инструменты. Выбор правильного программного обеспечения (ПО) для создания и ведения документации не менее важен, чем следование ГОСТам, так как именно инструмент позволяет поддерживать актуальность информации с минимальными трудозатратами.
Условно все инструменты можно разделить по их основной парадигме: "WYSIWYG-редакторы" (What You See Is What You Get — «что видишь, то и получаешь») и подход, основанный на использовании чистого текста (plain text) с языками разметки.
Традиционные WYSIWYG-редакторы и системы управления документами
Это классический подход, привычный для многих технических писателей.
Microsoft Word: Де-факто стандарт для создания отдельных документов (как ТЗ или Пояснительная записка). Его сильные стороны — повсеместная распространенность, мощные инструменты рецензирования и комментирования, возможность использования заранее подготовленных шаблонов, соответствующих ГОСТ (например, для оформления списков, таблиц и заголовков). Главный недостаток — сложность коллективной работы и поддержания актуальности версий. Документы быстро превращаются в набор файлов по типу "ТЗ_финальная_правки_Иванова_версия12.docx" и так далее. Так же их надо еще где то и хранить и делать резервные копии.
Google Docs: Решает ключевую проблему Word — коллективную работу. Несколько специалистов могут одновременно редактировать документ, оставлять комментарии и видеть историю изменений. Идеален для этапа черновой разработки и согласования текстов. Однако для финального оформления по строгим стандартам его возможностей может не хватить. Так же стоит сразу говорить о необходимой безопасности документации.
Confluence (от Atlassian) и похожие на это системы: Это уже не просто редактор, а целая корпоративная вики-система. Это мощный инструмент для создания структурированной, взаимосвязанной базы знаний. Отлично подходит для хранения всей документации проекта в одном месте: от технического задания и руководства пользователя до внутренних регламентов команды. Поддерживает вставку диаграмм, интеграцию с Jira, контроль версий страниц и разграничение прав доступа.
Gramax: Российская разработка основанная на GIT технологии с форматом хранения файлов markdown. Функционал системы очень богатый для работы с документацией, нет проблем с командной работой. Из минусов могу сказать только одно - если вы серьезно хотите работать с документацией нужно продумать структуру хранения. Во всем остальном система просто шикарна (сам пользуюсь на нескольких проектах команды довольны, заказчики в восторге).
Оbsidian: Это уже зарубежный аналог Gramax. Все тоже самое только в платном формате и чуть больше возможностей. Но учитывая что уже говорим о деньгах - становится не интересно. Много проектов где я использую данную системы, все прекрасно в бесплатном варианте умещаемся, но кое кто уже подумывает о Gramax.
Современный стек: Документация как код (Documentation as Code)
Это как раз о Gramax & Оbsidian в догонку к Redoc или Swagger. Мы говорим о создателях документации и программных продуктах.
Это парадигма, которая рождает огромную популярность, особенно в agile-командах. Ее суть в том, что документация пишется в виде текстовых файлов на легких языках разметки (как код), хранится в системе контроля версий (Git) и собирается в финальные форматы (HTML, PDF) с помощью специальных генераторов.
Преимущества подхода:
Версионность: Все изменения документации имеют историю, как и код программы. Можно легко увидеть, кто и что изменил, и откатиться к предыдущей версии.
Коллаборация: Процесс внесения правок происходит через механизм pull/merge requests, что обеспечивает ревью и контроль качества текста.
Автоматизация: Документацию можно автоматически собирать и публиковать при каждом новом коммите в репозиторий.
Единый инструмент: Разработчики и технические писатели работают в одной экосистеме (например, GitLab, GitHub), им не нужно переключаться между разными инструментами.
Ключевые инструменты этого стека:
Языки разметки:
Markdown (.md): Фактический стандарт для простой документации. Максимально простой синтаксис, читаемый даже в сыром виде. Поддерживается практически всеми генераторами и хостингами.
reStructuredText (.rst): Более мощный, но и более сложный конкурент Markdown.
Генераторы статических сайтов.
MkDocs: Очень простой и быстрый генератор, написанный на Python. Для сборки достаточно файла mkdocs.yml и папки с Markdown-файлами. Идеален для быстрого старта.
Sphinx: Мощный инструмент, изначально созданный для документации к Python, но теперь используемый для проектов на любых языках. Поддерживает сложные cross-references, генерацию индексов и вывод с множество форматов (HTML, PDF, ePub). Позволяет использовать директивы reStructuredText для более сложной разметки.
Docusaurus: Фреймворк от Facebook, ориентированный на документацию для открытых проектов. Предоставляет из коробки современный, реактивный дизайн, блог, режим переводов и другие возможности. Пробовал, но не зашло. Основное, что остановило это визуальная обертка всего функционала. За время небольшого petproject своего так и не смог оценить его фишки.
Хостинг и публикация.
GitHub Pages: Бесплатные сервисы для автоматического хостинга сгенерированной из репозитория документации. Достаточно настроить CI/CD-пайплайн, и ваша документация будет автоматически обновляться на сайте при каждом обновлении кода. Очень удобная система для команды разработчиком и проджектов.
Read the Docs: Самый популярный специализированный хостинг для технической документации. Автоматически собирает проекты с помощью Sphinx или MkDocs и предоставляет красивый, удобный интерфейс.
Российское программное обеспечение для работы с документацией
В свете требований по импортозамещению многие организации ищут отечественные аналоги. Российский рынок предлагает решения, которые могут успешно применяться для создания и управления технической документацией.
Р7-Офис и МойОфис: Это российский офисный пакет, являющиеся полнофункциональными аналогами MS Office. Они включают текстовый редактор "Р7-Редактор документов", который полностью подходит для создания и редактирования документов по ГОСТ в привычном формате ".docx". Поддерживают шаблоны, рецензирование и совместимы с форматами MS Word. Ключевое преимущество — соответствие требованиям регуляторов и возможность работы в изолированных средах.
«Редокс» (Redox): Это еще один продукт созданный Российскими разработчикам для управления документацией по стандартам ЕСПД и ГОСТ 34. Это не просто редактор, а комплексная система, которая позволяет:
- Предоставляет шаблоны документов в полном соответствии с ГОСТ 19 и 34.
- Автоматизирует оформление (нумерация, списки, заголовки).
- Управляет жизненным циклом документов (согласование, утверждение, выпуск).
- Интегрируется с системами электронного документооборота (СЭД).
Это профессиональное решение для крупных компаний, серьезно относящихся к формальным требованиям по документации.
Системы электронного документооборота (СЭД)
Это отдельная тема для разговора, но такие продукты, так же применяются для создания документации. Это целая экосистема взимосвязанных продуктов. СЭД может выполнять следующие функции:
- Создание, хранение, хлассификация и обработка докумтов в лбом объеме.
- Проыедуры согласования, подписания и рецензирования, а так же архивное хранение с сериализацией.
В системах СЭД могут применяться многожество форматов документов которые мы обсудили выше.
Главное — выбрать инструмент, который минимизирует рутину и позволит легко поддерживать документацию в актуальном состоянии, ведь ее ценность определяется не красотой оформления, а точностью и своевременностью информации.
Вместо итога можно было сказать что мы рассмотрели 0,1% от всего что нужно для создания правильной документации на продукт. Если тема действительно интересна и будет поддержана комментариями и лайками, готов буду добавить пару статей в бесплатном варианте.