Документация к программному обеспечению

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

Существует и другая классификация документов на программную систему:

  • Некоторые документы (например, документ спецификации требований и планы проектирования / конструирования компонентов системы) описывают процессы разработки. Эти документы — часть системной документации.
  • Остальные документы описывают продукты процессов разработки. Эти документы могут быть как системными (например, UML-схемы модулей системы), так и пользовательскими (например, руководства по использованию).

Презентация:Лекция 16.

Согласно гибкой методологии разработки, объем документации на систему, в особенности описывающей процессы, должен быть сведен к минимуму. На составление исчерпывающей документации уходит много времени и средств; из-за высокой скорости эволюции структура программной системы меняется настолько быстро, что документация устаревает практически сразу после выхода. Разумеется, полностью отказаться от документации нельзя: в любом случае сохраняется потребность в пользовательской документации, такой как руководства.

Документация к современным системам доступна в нескольких форматах:

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

Электронная документация, которая может быть локальной (например, Readme-файлы) или встраиваться в глобальную систему документации (man, help и так далее). По сравнению с печатной документацией, электронные документы могут быть более детальными; в них легче проводить поиск по ключевым словам.

Документация, размещенная в Интернете. К этому виду документации относятся не только составленные разработчиками и размещенные на сайте продукта материалы (Getting started, справочные руководства и тому подобное), но и документы, генерируемые пользователями системы. К такой Web 2.0-документации относятся wiki по программным продуктам, записи в блогах, ответы на сайтах вроде stackoverflow и так далее.

Документацию можно писать вручную с использованием систем редактирования и верстки (например, Microsoft Word или LaTeX). Более продуктивный способ — использование генераторов вроде Javadoc и Doxygen. В этом случае документирование осуществляется в исходных файлах программной системы, чаще всего в виде специальных комментариев (хотя возможны другие варианты, например, строки документации в Python). Такую документацию можно читать при просмотре исходного кода программы; она же используется для контекстной помощи в средах разработки. Наконец, при помощи генератора документацию можно выделить в отдельные документы (например, HTML или страницы man).

Развитие идеи комментирования исходного кода программы — грамотное программирование (literate programming), придуманное Дональдом Кнутом для системы TeX. В этом подходе роли комментариев и кода меняются: текст программы представляет собой эссе на естественном языке с отдельными фрагментами кода. С помощью специальных инструментов код выделяется из эссе и формирует исходный код на определенном языке программирования; после этого можно проводить компиляцию и т. д. Грамотное программирование позволяет проследить ход мысли разработчика программы, лучше понять ее структуру и решения, принятые при разработке. При всех своих преимуществах, грамотное программирование применяется редко — не все программисты любят писать эссе.

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

Документация разработки программного продукта

Состав документации разработки программного продукта в значительной мере зависит от методологии, которую исповедует коллектив разработчиков. Каждая методология, скажем, RUP или MSF, предусматривает свой набор документов. Идеологически эти наборы во многом похожи, хотя одни и те же документы в них могут по-разному называться и иметь разную структуру.

В Единой системе программной документации понятие документации разработки отсутствует, но как таковая она там предусмотрена. В табл.

1 приведен состав документации разработки согласно ЕСПД.

Таблица 1. Документация разработки программы согласно ЕСПД

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

Эксплуатационная документация на программный продукт

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

Наиболее распространенные типы эксплуатационных документов приведены в табл. 2.

Таблица 2. Эксплуатационная документация на программный продукт

Документ Аудитория
описание программы лица, принимающие решения о приобретении, вводе в эксплуатацию и способах использования программы назначение и основные возможности программы, необходимые ей нее системные ресурсы, входные и выходные данные
описание применения
описание языка пользователи языка (программисты, операторы, кодеры, верстальщики) основная идея языка, его синтаксис, элементы и конструкции, встроенные функции
паспорт лица, ответственные за эксплуатацию программы краткие сведения о программе и условиях ее поставки
руководство администратора ответственный пользователь системы, обеспечивающий ее целевое применение управление учетными записями пользователей, назначение пользователям прав доступа, ведение нормативно-справочной информации, загрузка и выгрузка данных
руководство оператора операторы, работающие с системой, частью которой является программа порядок выполнения предусмотренных операций, сообщения программы и предписанные оператору способы реакции на них
руководство пользователя пользователи программы, т.е. лица, применяющие ее для решения собственных прикладных задач назначение и возможности программы, ее основные концепции, интерфейс пользователя, порядок решения типовых задач, описание функций программы
руководство программиста программисты, сопровождающие программу или использующие ее в качестве платформы либо средства разработки при создании собственных программ архитектура программы или создаваемых на ее основе приложений, описание программных интерфейсов к ее объектам, протоколов обмена данными и т. п.
руководство системного администратора (системного программиста) системные администраторы, осуществляющие установку программы и поддерживающие систему в рабочем состоянии установка программы, ее интеграция в систему, проверка правильности функционирования, устранение аварийных ситуаций
спецификация лица, ответственные за эксплуатацию программы комплект поставки программы
справочная система («хелп») пользователи, операторы, администраторы, системные администраторы, программисты и др. материал всех имеющихся руководств и описаний, краткие описания элементов интерфейса пользователя программы
формуляр лица, ответственные за эксплуатацию программы краткие сведения о программе и условиях ее поставки, записи эксплуатационного о возникающих сбоях и прочих событиях такого рода

Документирование ПО

Когда программист-разработчик получает в той или иной форме задание на программирование, перед ним, перед руководителем проекта и перед всей проектной группой встают вопросы:

· что должно быть сделано, кроме собственно программы?

· что и как должно быть оформлено в виде документации?

· что передавать пользователям, а что службе сопровождения?

· как управлять всем этим процессом?

· что должно входить в само задание на программирование?

Кроме упомянутых вопросов есть и другие.

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

В настоящее время остается актуальным вопрос о наличии системы, регламентирующей документирование программных средств (ПС).

Обзор отечественных стандартов по составлению документации на ПО

Основу отечественной нормативной базы в области документирования ПС составляет комплекс стандартов Единой системы программной документации (ЕСПД).

Основная и большая часть комплекса ЕСПД была разработана в 70-е и 80-е годы. Сейчас этот комплекс представляет собой систему межгосударственных стандартов стран СНГ (ГОСТ), действующих на территории Российской Федерации на основе межгосударственного соглашения по стандартизации.

Стандарты ЕСПД в основном охватывают ту часть документации, которая создается в процессе разработки ПС, и связаны, по большей части, с документированием функциональных характеристик ПС. Следует отметить, что стандарты ЕСПД (ГОСТ 19) носят рекомендательный характер. Впрочем, это относится и ко всем другим стандартам в области ПС (ГОСТ 34, Международному стандарту ISO/IEC, и др.). Дело в том, что в соответствии с Законом РФ «О стандартизации» эти стандарты становятся обязательными на контрактной основе — то есть при ссылке на них в договоре на разработку (поставку) ПС.

Говоря о состоянии ЕСПД в целом, можно констатировать, что большая часть стандартов ЕСПД морально устарела.

К числу основных недостатков ЕСПД можно отнести:

  • ориентацию на единственную, «каскадную» модель жизненного цикла (ЖЦ) ПС;
  • отсутствие четких рекомендаций по документированию характеристик качества ПС;
  • отсутствие системной увязки с другими действующими отечественными системами стандартов по ЖЦ и документированию продукции в целом, например, ЕСКД;
  • нечетко выраженный подход к документированию ПС как товарной продукции;
  • отсутствие рекомендаций по самодокументированию ПС, например, в виде экранных меню и средств оперативной помощи пользователю («хелпов»);
  • отсутствие рекомендаций по составу, содержанию и оформлению перспективных документов на ПС, согласованных с рекомендациями международных и региональных стандартов.

Ниже рассмотрены наиболее используемые стандарты в практике:


1) ГОСТ (СТ СЭВ) 19.201-78 (1626-79). ЕСПД. Техническое задание. Требование к содержанию и оформлению.

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

Техническое задание должно содержать следующие разделы:

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

ГОСТ (СТ СЭВ) 19.101-77 (1626-79). ЕСПД. Виды программ и программных документов.

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

· Виды программ

· Виды программных документов

· Виды эксплуатационных документов

· Виды программных документов, разрабатываемых на разных стадиях, и их коды


3) ГОСТ 19.102-77. ЕСПД. Стадии разработки.

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

· Техническое задание: постановка задачи, сбор материалов

· Эскизный проект: уточнение методов решения

· Технический проект: разработка алгоритма, структуры программы

· Рабочий проект программирование, разработка документации, тестирование

· Внедрение: передача программы для изготовления и/или сопровождения

Документация на программное обеспечение — печатные руководства пользователя, диалоговая (оперативная) документация и справочный текст, описывающие, как пользоваться программным продуктом.
Документ — элемент документации: целевая информация, предназначенная для конкретной аудитории, размещенная на конкретном носителе (например, в книге, на диске, в краткой справочной карте) в заданном формате.

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

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

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

Часто при составлении технической документации используются автоматизированные средства — генераторы документации, такие как Doxygen, javadoc, NDoc и другие. Они получают информацию из специальным образом оформленных комментариев в исходном коде, и создают справочные руководства в каком-либо формате, например, в виде текста или HTML.

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

Пользовательская документация

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

Обычно, пользовательская документация представляет собой руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идёт ещё дальше и предоставляет
инструкции о том, что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение. Существует три подхода к организации пользовательской документации. Вводное руководство (англ. tutorial), наиболее полезное для новых пользователей, последовательно проводит по ряду шагов, служащих для выполнения каких-либо типичных задач. Тематический подход, при котором каждая глава руководства посвящена какой-то отдельной теме, больше подходит для совершенствующихся пользователей. В последнем, третьем подходе, команды или задачи организованы в виде алфавитного справочника — часто это хорошо воспринимается продвинутыми пользователями, хорошо знающими, что они ищут. Жалобы пользователей обычно относятся к тому, что документация охватывает только один из этих подходов, и поэтому хорошо подходит лишь для одного класса пользователей.
Во многих случаях разработчики программного продукта ограничивают набор пользовательской документации лишь встроенной системой помощи (англ. online help), содержащей справочную информацию о командах или пунктах меню. Работа по обучению новых пользователей и поддержке совершенствующихся пользователей перекладывается на частных издателей, часто оказывающих значительную помощь разработчикам.

Добавить комментарий

Закрыть меню