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

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

Что называют техдокументацией

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

Чем полезна

1. Удобство. С ее помощью можно отслеживать каждый этап разработки. В таком случае легко вспомнить о проделанной работе, если создание ПО по какой-либо причине приостановилось.
2. Кодовая проверка. Используя техдокументацию, программы анализируют функции, логику определенной части кода. С такой возможностью проще обслуживать или настраивать программу.
3. Передача знаний. Документы особенно важны, если в работе над ПО начинает участвовать новый работник или нужно работать с проектов, над которым работали другие люди.
4. Увеличение производительности. Работа пойдет гораздо проще, а задачи удастся выполнить быстрее, если документация будет подробной.
5. Аргументация в спорных ситуациях.Позволяет обосновать решения, если вы столкнулись с неоднозначными решениями в техзадании заказчика.

Виды

Существует 3 вида документации:

1. Пользовательская. Речь идет об описании задачи и функций программы, а также пошаговых инструкциях по ее использованию. Это может быть руководство для пользователей, техпаспорт и прочие материалы, необходимые для работы с программой.
2. Технологическая. В ней собрано все, что может понадобиться для изменений, настроек и поддержания функциональности ПО. Речь идет об исходном коде, комментариях к нему, дизайн-макетах интерфейсов, примерах и причинах ошибок в работе. Чаще ее пишут для API, структур данных.
3. Проектная. Объясняет, почему было принято определенное решение. В ней можно выделить паттерны, которые применялись при проектировании, а также представить варианты для улучшений.

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

Госорганизации, которые занимаются проектированием ПО, или специалисты, создающие программы по заказу государственных компаний, обязаны составлять техдокументацию. Нередко в требованиях указано, что она должна быть составлена в соответствии с ГОСТами. Главный нормативный акт – ГОСТ 19.101-2020 ЕСПД. Согласно этому акту необходимо указывать:

• спецификацию;
• ведомость держателей подлинников;
• характеристики программы;
• методику тестирования;
• техзадания;
• записку-пояснение;
• документы по эксплуатации.

Если речь идет о работе с компаниями негосударственного типа, то содержание будет зависеть от самого ПО, ЦА и условий заказчика. Документы могут содержать:

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

Каким сферам может пригодиться разработка документации для ПО

1. ИТ-бизнесу, если в компании занимаются разработкой новых продуктов, планируют обеспечить клиентов качественной документацией.
2. Командам разработчиков, которые работают над созданием крупных проектов.
3. Корпорациям и предприятиям, которые пользуются сложными программными решениями. В этом случае особенно актуальна будет подробная документация.
4. Отдельным специалистам, если их работа связана с личными проектами.
5. Образовательным учреждениям, которые обучают студентов и преподавателей работе с ПО. 
6. Госорганизациям и ведомствам, работающим над внедрением новых программных систем и нуждающимся в инструкциях и руководстве по их использованию.
7. Инвесторам и аналитикам, которые нуждаются в подробной и понятной инструкции, чтобы оценить, проанализировать ПО.
8. Руководству и проект-менеджерам, которые хотят повысить успешность выполнения проектной деятельности, а также эффективность командной работы.

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

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

1. Время создания. Лучше писать в процессе разработки, а не после. Так вам удастся задокументировать все детали и не ошибиться. Исключением является составление эл.документов для госорганизаций, банков – чаще требуют предоставлять их до разработки.
2. ЦА. От целевой аудитории будет зависеть язык написания. Например, если вы пишете руководство, то текст должен получится понятным, без сложных терминов из сферы программирования. Для проектной и техдокументации нужно использовать фрагменты кода, язык разработки.
3. Оглавление. Объем может насчитывать десятки страниц, поэтому лучше добавить оглавление с ссылками на разделы. Это позволит читателю попасть на нужную страницу.
4. Дату обновления. Дата и версия последнего обновления подтвердят актуальность указанной информации.
5. Полноценную информацию. При добавлении примеров кода не забудьте описать нужный фрагмент – так он при копировании будет срабатывать верно.
6. Краткость. Придерживайтесь сухого языка, откажитесь от лишней информации.
7. Актуальность. Не указывайте код, если его уже не используют в ПО. Если предполагаете, что в будущем он может понадобиться, то стоит сохранить его в системе контроля версий.
8. Визуальная составляющая. Не лишним будет использование таблиц, диаграмм и схем – главное, чтобы это было уместно. Это решение позволит проще воспринимать данные.

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

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

Doxygen

Сервисом можно пользоваться бесплатно. Он проводит анализ исходного кода, комментариев к нему, а также автоматически способен извлекать данные о классах, функциях, переменных и прочих элементах. Чаще его используют для C# и C++, но также поддерживает иные языки, в особенности Python, Java, IDL, PHP. 

Sphinx

С помощью этого инструмента можно генерировать техдокументацию из исходного кода на различных языках программирования, в том числе Python, C++ и Java. Он использует спецязык разметки reStructuredText, чтобы описывать структуру и содержание ПО. С помощью этого языка можно легко создать оглавление, список, таблицу и прочие элементы. Также в инструменте предусмотрена возможность формирования интерактивных документов с графиками, диаграммами.

Adobe RoboHelp

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

GitHub

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

GitBook

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

Confluence

Бесплатный инструмент для совместной работы. Он рассчитан на создание и редактирование документации в режиме реального времени. В программе предусмотрены готовые шаблоны, которые можно настраивать под себя. Кроме того, можно добавить плагины, макросы. Инструмент подходит для интеграции с разными сервисами, например, такими как Git, Jira или Bitbucket.

Javadoc

Генератор для разработки технической документации программного обеспечения. Встроен в Java. Его используют для генерации техдокументации API из исходного кода. Команда осуществляет код ПО, извлекает данные о комментариях, а затем их преобразует в документацию.