Документация к программному обеспечению: типы и важность требований

Введение

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

Требования – Описания, определяющие атрибуты, возможности, характеристики или качества системы. Это основа для того, что будет или уже реализовано. Архитектура/Проектирование – Обзор программного обеспечения, включая его взаимодействие с окружением и принципы построения программных компонентов. Техническая документация – Описание кода, алгоритмов, интерфейсов и API. Документация для конечного пользователя – Руководства для конечных пользователей, системных администраторов и специалистов службы поддержки. Маркетинговая документация – Информация о продвижении продукта и анализе рыночного спроса.

Документация требований

Документация требований – это описание того, что программное обеспечение делает или должно делать. Она используется на протяжении всего процесса разработки для передачи информации о функционировании программного обеспечения или о том, как оно должно работать. Она также служит соглашением или основой для достижения согласия относительно функциональности программного обеспечения. Требования создаются и используются всеми участниками процесса разработки программного обеспечения, включая: конечных пользователей, заказчиков, менеджеров проектов, отделы продаж и маркетинга, архитекторов программного обеспечения, специалистов по юзабилити, дизайнеров взаимодействия, разработчиков и тестировщиков. Требования могут быть представлены в различных стилях, нотациях и с разной степенью формализации. Они могут быть сформулированы как цели (например, распределенная рабочая среда), приближены к дизайну (например, запуск сборки через контекстное меню файла конфигурации с выбором функции "создать") или занимать промежуточное положение. Требования могут быть выражены в виде утверждений на естественном языке, графических схем, подробных математических формул или их комбинации. Разнообразие и сложность документации требований представляют собой серьезную проблему. Требования могут быть неявными и трудно выявляемыми. Сложно определить необходимый объем и тип документации, а также то, какую часть информации можно оставить для архитектурной и проектной документации. Кроме того, сложно учесть потребности различных категорий пользователей, которые будут читать и использовать документацию. В результате документация требований часто бывает неполной или вовсе отсутствует. Без надлежащей документации требований внесение изменений в программное обеспечение становится более сложным – и, следовательно, более подверженным ошибкам (снижение качества программного обеспечения) и требующим больших затрат времени (и средств). Необходимость в документации требований обычно определяется сложностью продукта, его влиянием и ожидаемым сроком службы. Если программное обеспечение сложное или разрабатывается большой командой (например, программное обеспечение для мобильных телефонов), требования помогают лучше понять, чего необходимо достичь. Если программное обеспечение критически важно для безопасности и может негативно повлиять на жизнь людей (например, системы управления ядерными электростанциями, медицинское оборудование, механическое оборудование), требуется более формальная документация требований. Если ожидаемый срок службы программного обеспечения невелик (например, небольшие мобильные приложения, разработанные для конкретной рекламной кампании), может потребоваться минимальный объем документации требований. Если программное обеспечение является первым релизом, на основе которого будет вестись дальнейшая разработка, документация требований будет полезна для управления изменениями и проверки отсутствия ошибок при модификации программного обеспечения. Традиционно требования фиксируются в документах с требованиями (например, с использованием текстовых и табличных редакторов). Для управления возрастающей сложностью и изменчивостью документации требований (и документации программного обеспечения в целом) рекомендуется использовать системы управления базами данных и специализированные инструменты управления требованиями. В гибкой разработке программного обеспечения требования часто выражаются в виде пользовательских историй с сопутствующими критериями приемки.

Requirements documentation is the description of what a particular software does or shall do. It is used throughout development to communicate how the software functions or how it is intended to operate. It is also used as an agreement or as the foundation for agreement on what the software will do. Requirements are produced and consumed by everyone involved in the production of software, including: end users, customers, project managers, sales, marketing, software architects, usability engineers, interaction designers, developers, and testers. Requirements come in a variety of styles, notations and formality. Requirements can be goal like (e. g., distributed work environment), close to design (e. g., builds can be started by right clicking a configuration file and selecting the 'build' function), and anything in between. They can be specified as statements in natural language, as drawn figures, as detailed mathematical formulas, or as a combination of them all. The variation and complexity of requirement documentation make it a proven challenge. Requirements may be implicit and hard to uncover. It is difficult to know exactly how much and what kind of documentation is needed and how much can be left to the architecture and design documentation, and it is difficult to know how to document requirements considering the variety of people who shall read and use the documentation. Thus, requirements documentation is often incomplete (or non existent). Without proper requirements documentation, software changes become more difficult — and therefore more error prone (decreased software quality) and time consuming (expensive). The need for requirements documentation is typically related to the complexity of the product, the impact of the product, and the life expectancy of the software. If the software is very complex or developed by many people (e. g., mobile phone software), requirements can help better communicate what to achieve. If the software is safety critical and can have a negative impact on human life (e. g., nuclear power systems, medical equipment, mechanical equipment), more formal requirements documentation is often required. If the software is expected to live for only a month or two (e. g., very small mobile phone applications developed specifically for a certain campaign) very little requirements documentation may be needed. If the software is a first release that is later built upon, requirements documentation is very helpful when managing the change of the software and verifying that nothing has been broken in the software when it is modified. Traditionally, requirements are specified in requirements documents (e. g. using word processing applications and spreadsheet applications). To manage the increased complexity and changing nature of requirements documentation (and software documentation in general), database centric systems and special purpose requirements management tools are advocated. In Agile software development, requirements are often expressed as User Stories with accompanying acceptance criteria.

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

Важно, чтобы документация, связанная с исходным кодом (которая может включать файлы README и документацию API), была полной, но не чрезмерно подробной, чтобы её сопровождение не отнимало слишком много времени и не было сложным. Различные руководства и обзоры документации часто создаются для конкретного программного приложения или продукта, документируемого разработчиками API. Эту документацию могут использовать разработчики, тестировщики и конечные пользователи. В настоящее время высокотехнологичные приложения широко распространены в таких областях, как энергетика, транспорт, сети, аэрокосмическая промышленность, безопасность, промышленная автоматизация и многие другие. Техническая документация стала критически важной для таких организаций, поскольку основная и углубленная информация может меняться со временем в связи с изменениями в архитектуре. Есть данные, подтверждающие, что наличие качественной документации к коду действительно снижает затраты на его поддержку. Документация к коду часто структурирована в виде справочного руководства, позволяющего программисту быстро находить информацию о любой функции или классе.

Техническая документация, встроенная в исходный код

Часто такие инструменты, как Doxygen, NDoc, Visual Expert, Javadoc, JSDoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText или Universal Report, могут использоваться для автоматической генерации документации по коду, то есть они извлекают комментарии и программные контракты (если они доступны) из исходного кода и создают справочные руководства в таких форматах, как текстовые или HTML-файлы. Идея автоматической генерации документации привлекательна для программистов по ряду причин. Например, поскольку документация извлекается непосредственно из исходного кода (например, из комментариев), программист может писать её, ориентируясь на код, и использовать те же инструменты, что и для создания самого кода, для создания документации. Это значительно упрощает поддержание документации в актуальном состоянии. Возможный недостаток заключается в том, что редактировать такую документацию могут только программисты, и именно они отвечают за обновление результатов генерации (например, путем запуска задания cron для ежедневного обновления документации). Некоторые могут рассматривать это скорее как преимущество, чем как недостаток.

Грамотный программирование

Уважаемый учёный-компьютерщик Дональд Кнут отмечал, что документирование зачастую представляет собой сложный процесс, выполняемый уже после написания кода, и выступал за методологию "литературного программирования", когда документация создаётся одновременно и в том же месте, что и исходный код, а затем извлекается автоматически. Языки программирования Haskell и CoffeeScript имеют встроенную поддержку простого варианта "литературного программирования", однако эта поддержка не получила широкого распространения.

Разъяснительное программирование

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

Документация пользователя

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

Unlike code documents, user documents simply describe how a program is used. In the case of a software library, the code documents and user documents could in some cases be effectively equivalent and worth conjoining, but for a general application this is not often true. Typically, the user documentation describes each feature of the program, and assists the user in realizing these features. It is very important for user documents to not be confusing, and for them to be up to date. User documents do not need to be organized in any particular way, but it is very important for them to have a thorough index. Consistency and simplicity are also very valuable. User documentation is considered to constitute a contract specifying what the software will do. API Writers are very well accomplished towards writing good user documents as they would be well aware of the software architecture and programming techniques used. See also technical writing. User documentation can be produced in a variety of online and print formats. However, there are three broad ways in which user documentation can be organized. Tutorial: A tutorial approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks. Thematic: A thematic approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user. Some authors prefer to convey their ideas through a knowledge based article to facilitate the user needs. This approach is usually practiced by a dynamic industry, such as Information technology. List or Reference: The final type of organizing principle is one in which commands or tasks are simply listed alphabetically or logically grouped, often via cross referenced indexes. This latter approach is of greater use to advanced users who know exactly what sort of information they are looking for. A common complaint among users regarding software documentation is that only one of these three approaches was taken to the near exclusion of the other two. It is common to limit provided software documentation for personal computers to online help that gives only reference information on commands or menu items. The job of tutoring new users or helping more experienced users get the most out of a program is left to private publishers, who are often given significant assistance by the software developer.

Составление пользовательской документации

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

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

Маркетинговая документация

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

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

Споры о документации и гибкой разработке

Сопротивление разработчиков ведению документации хорошо известно и не требует дополнительных акцентов. Эта ситуация особенно распространена в гибкой разработке программного обеспечения, поскольку эти методологии стремятся избегать любых излишних действий, которые не приносят прямой ценности. В частности, Agile Manifesto провозглашает приоритет "рабочего программного обеспечения над исчерпывающей документацией", что может быть цинично истолковано как "Мы хотим тратить все время на написание кода. Помните, настоящие программисты не пишут документацию". Однако опрос экспертов в области разработки программного обеспечения показал, что документация отнюдь не считается ненужной в гибкой разработке. При этом признается, что в разработке существуют проблемы с мотивацией, и могут потребоваться методы документирования, адаптированные к гибким методологиям (например, с использованием систем репутации и геймификации).