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

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

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

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

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

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

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

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

Научиться грамотно составлять техническую документацию на программное обеспечение с учётом требований заказчика, анализировать и структурировать данные, а также готовить инструкции для разработки можно на курсе «Системный аналитик». Во время обучения студенты выполняют задания, близкие к реальным рабочим задачам, а по итогам курса добавляют в портфолио 5 проектов и 9 практических работ.

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

Документацию на программное обеспечение можно разделить на три вида:

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

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

При составлении любого вида технической документации на программное обеспечение стоит обратить внимание на:

● Время создания. Документацию лучше начинать писать во время разработки ПО, а не после. Это позволит точно задокументировать детали создания программы, логику решений и снизит вероятность неверной информации. Исключение — составление технической документации ПО для госкомпаний и банков, которые часто требуют предоставить её до начала процесса разработки.
● Целевую аудиторию. От этого зависит язык, которым пишется документация. Например, текст руководства для пользователей должен быть понятным и не содержать множества терминов из области программирования. А в проектной и технической документации ПО нужно использовать язык разработки и фрагменты кода.
● Оглавление. Документация на программное обеспечение может насчитывать несколько десятков страниц, поэтому полезно добавить оглавление со ссылками на разделы, чтобы читатель мог сразу перейти к нужной части.
● Дату обновления. Для того чтобы пользователи и составитель технической документации ПО были уверены, что в ней содержится актуальная информация, стоит указать в названии документа дату и версию его последнего обновления.
● Полноценные данные. В технической документации ПО обычно есть много примеров кода. При их добавлении важно описывать весь необходимый фрагмент кода, чтобы при копировании он срабатывал верно.
● Краткость. Чем меньше лишней информации в документации, тем больше вероятность, что её действительно прочитают. При этом в тексте лучше придерживаться сухого языка и воздержаться от витиеватых выражений и шуток.
● Актуальность. Не стоит отражать в технической документации код, который уже не используется в программном обеспечении. Если есть вероятность, что старый код понадобится в будущем, его можно сохранить в системе контроля версий.
● Визуал. Полезно использовать таблицы, диаграммы и схемы там, где это уместно. Так читателям документации ПО будет проще воспринимать информацию.

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

● Doxygen. Бесплатный сервис, который анализирует исходный код и комментарии к нему, автоматически извлекает информацию о классах, функциях, переменных и других элементах программы. В основном используется для C# и C++, но также поддерживает другие языки, в том числе Python, Java, IDL и PHP.

Doxygen позволяет создавать документацию в различных форматах, например HTML или RTF, а также конвертировать данные в PDF. Источник: Doxygen.nl

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

Sphinx позволяет создавать документацию в различных форматах, например HTML, PDF или ePub. Источник: Sphinx

● Adobe RoboHelp. Программа для создания справок, руководств для пользователей и другой технической документации ПО. С её помощью можно добавлять изображения, таблицы, диаграммы и другие элементы, а также настраивать внешний вид и структуру документа. Стоимость: от $40 в месяц, есть пробная версия.

В RoboHelp можно составлять документацию в формате CHM и PDF. Источник: Adobe Technical Communication

● GitHub. Система контроля версий GitHub позволяет создавать и поддерживать техническую документацию на программное обеспечение, а также даёт возможность совместной разработки. Там можно комментировать код, интегрировать его изменения, структурировать текст документации, добавлять таблицы, схемы и выделять блоки кода. Стоимость: от $4 в месяц, есть бесплатная версия.

GitHub даёт возможность бесплатно размещать проекты с открытым исходным кодом. Источник: GitHub

● GitBook. Платформа, которая позволяет нескольким авторам работать над одной документацией одновременно. Включает настраиваемые темы и шаблоны, функцию поиска и имеет простой интерфейс. Удобна для создания всех видов технической документации ПО. Стоимость: от $6,7 в месяц, есть бесплатная версия.

GitBook поддерживает несколько форматов итоговой документации, включая HTML, PDF и форматы электронных книг EPUB и MOBI. Источник: GitBook

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

В Confluence можно выгрузить готовую техническую документацию в формате Word, PDF, HTML или XML. Источник: Atlassian.com

● Javadoc. Генератор технической документации API из исходного кода, встроенный в язык программирования Java. Команда Javadoc анализирует код ПО и извлекает информацию о комментариях, которые начинаются с /** и заканчиваются */. Затем эти данные преобразуются в документацию.

Вся документация Javadoc обрабатывается в виде HTML. Источник: Wikipedia