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

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

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

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

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

Типы документации

Существует четыре основных типа документации на ПО:

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

Архитектурная/проектная документация

Проектная документация обычно описывает продукт в общих чертах. Не описывая того, как что-либо будет использоваться, она скорее отвечает на вопрос «почему именно так?» Например, в проектном документе программист может описать обоснование того, почему структуры данных организованы именно таким образом. Описываются причины, почему какой-либо класс сконструирован определённым образом, выделяются паттерны, в некоторых случаях даже даются идеи как можно будет выполнить улучшения в дальнейшем. Ничего из этого не входит в техническую или пользовательскую документацию, но всё это действительно важно для проекта.

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

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

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

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

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

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

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

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

Обычно, пользовательская документация представляет собой руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идёт ещё дальше и предоставляет инструкции о том что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение.

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

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

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

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

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

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

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

Примечания

1. ↑ 12 ГОСТ Р ИСО/МЭК 15910-2002 — Процесс создания документации пользователя программного средства
2. ↑ГОСТ 19781—90 Единая система программной документации. Обеспечение систем обработки информации программное

См. также

Ссылки

Кент Бек • Гради Буч • Фред Брукс • Barry Boehm • Уорд Каннингем • Оле-Йохан Даль • Том Демарко • Эдсгер Вибе Дейкстра • Дональд Кнут • Мартин Фаулер • Чарльз Энтони Ричард Хоар • Watts Humphrey • Майкл Джексон • Ивар Якобсон • Craig Larman • James Martin • Мейер Бертран • Дэвид Парнас • Winston W. Royce • James Rumbaugh • Никлаус Вирт • Эдвард Йордан • Стив Макконнелл

Моделирование данных • Архитектура ПО • Функциональная спецификация • Язык моделирования • Парадигма • Методология • Процесс разработки • Качество • Обеспечение качества • Структурный анализ)

CMM • CMMI • Данных • Function model • IDEF • Информационная • Metamodeling • Object model • View model • UML

• Техническая документация
• Программное обеспечение
• Разработка программного обеспечения

Wikimedia Foundation . 2010 .

Полезное

Смотреть что такое «Документация на программное обеспечение» в других словарях:

• Программное обеспечение — Запрос «Software» перенаправляется сюда; см. также другие значения … Википедия
• программное обеспечение — 01.01.80 программное обеспечение (в области электросвязи) [software ]: Программы ЭВМ, процедуры, правила и любая сопутствующая документация, имеющие отношение к работе аппаратуры, сети электросвязи или другого… … Словарь-справочник терминов нормативно-технической документации
• программное обеспечение (ПО) — 3.34 программное обеспечение (ПО) (software): Программы (т.е. набор упорядоченных команд), данные, правила и любая связанная с этим документация, имеющая отношение к работе компьютеризированной системы контроля и управления. [МЭК 62138, пункт… … Словарь-справочник терминов нормативно-технической документации
• ГОСТ Р МЭК 60880-2010: Атомные электростанции. Системы контроля и управления, важные для безопасности. Программное обеспечение компьютерных систем, выполняющих функции категории А — Терминология ГОСТ Р МЭК 60880 2010: Атомные электростанции. Системы контроля и управления, важные для безопасности. Программное обеспечение компьютерных систем, выполняющих функции категории А оригинал документа: 3.25 N версионное программное… … Словарь-справочник терминов нормативно-технической документации
• Документация — Документация это совокупность данных и документов. В узко профессиональном значении Документация (документирование) процесс отбора, классификации, использования и распространения документов. Работа специалиста по подбору документации… … Википедия
• ПРОГРАММНОЕ СРЕДСТВО — 6. ПРОГРАММНОЕ СРЕДСТВО по ГОСТ 28806 90. Источник: РБ 004 98: Требования к сертификации управляющих систем, важных для безопасности атомных станций … Словарь-справочник терминов нормативно-технической документации
• обеспечение — Процесс скоординированного управления по обеспечению всех материалов и ресурсов, требуемых для эксплуатации изделия. Источник: ГОСТ Р 53480 2009: Надежность в технике. Термины и определения оригинал документа … Словарь-справочник терминов нормативно-технической документации
• Стадия «Рабочая документация» — 2.6. Стадия «Рабочая документация» 2.6.1. Задачей стадии является разработка технической рабочей документации, обеспечивающей выполнение работ по вводу АС в действие. На данном этапе должны быть также все документы, необходимые при эксплуатации… … Словарь-справочник терминов нормативно-технической документации
• Canon EOS 30D — Тип цифровой зеркальный фотоаппарат Матрица КМОП 22,5 × 15,0 мм (Kf = 1,6) … Википедия
• Canon EOS 600D — Canon EOS Digital Rebel T3i Canon EOS Kiss X5 Тип DSLR … Википедия

• Обратная связь: Техподдержка, Реклама на сайте

• �� Путешествия

Экспорт словарей на сайты, сделанные на PHP,
WordPress, MODx.

• Пометить текст и поделитьсяИскать в этом же словареИскать синонимы
• Искать во всех словарях
• Искать в переводах
• Искать в ИнтернетеИскать в этой же категории

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

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

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

• 1 Документация по требованиям
• 2 Документация по проектированию архитектуры
• 3 Техническая документация
  • 3.1 Техническая документация, встроенная в исходный код
    • 3.1.1 Грамотное программирование
    • 3.1.2 Разъяснительное программирование
    • 4.1 Составление пользовательской документации

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

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

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

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

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

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

    Архитектурная проектная документация

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

    Другой тип проектной документации — это сравнительный документ или коммерческое исследование. Часто это принимает форму whitepaper. Он фокусируется на одном конкретном аспекте системы и предлагает альтернативные подходы. Это может быть пользовательский интерфейс, код, дизайн или даже архитектура. В нем будет описана ситуация, описана одна или несколько альтернатив и перечислены плюсы и минусы каждой из них. Хороший учебный документ по торговле содержит большое количество исследований, ясно выражает свою идею (без сильной опоры на тупой жаргон, чтобы ослепить читателя) и, что наиболее важно, беспристрастен. Он должен честно и четко объяснять стоимость любого предлагаемого решения. Цель торгового исследования состоит в том, чтобы разработать лучшее решение, а не продвигать определенную точку зрения. Совершенно приемлемо не делать никаких выводов или делать вывод о том, что ни одна из альтернатив не является достаточно лучшей, чем базовая линия, чтобы гарантировать изменение. К нему следует подходить как к научному начинанию, а не как к маркетинговому методу.

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

    • Разработчик базы данных
    • Разработчик базы данных
    • Администратор базы данных
    • Разработчик приложения
    • Разработчик приложения

    Когда речь идет о Relational Database Systems, документ должен включать следующие части:

    • Сущность — Схема отношений (расширенная или нет), включая следующую информацию и их четкие определения:
      • Наборы сущностей и их атрибуты
      • Отношения и их атрибуты
      • Ключи-кандидаты для каждого набора сущностей
      • Ограничения на основе атрибутов и кортежей
      • Таблицы, атрибуты, и их свойства
      • Представления
      • Ограничения, такие как первичные ключи, внешние ключи,
      • Мощность ссылочных ограничений
      • Политика каскадирования для ссылочных ограничений
      • Первичные ключи

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

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

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

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

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

      Часто инструменты, такие как Doxygen, NDoc, Visual Expert, Javadoc, JSDoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText или универсальный отчет можно использовать для автоматического создания документов кода, то есть они извлекают комментарии и программные контракты, если таковые имеются, из исходного кода и создают справочники в виде текста или файлов HTML.

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

      Конечно, недостатком является то, что только программисты могут редактировать подобную документацию, и от них зависит обновление вывода (например, запустив задание cron для обновления документов каждую ночь). Некоторые охарактеризовали бы это как за, а не как против.

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

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

      Пояснительное программирование

      Пояснительное программирование — это результат практического применения грамотного программирования в реальных контекстах программирования. Парадигма Elucidative предлагает хранить исходный код и документацию отдельно.

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

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

      В отличие от кодовых документов, пользовательские документы просто описывают, как используется программа.

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

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

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

      1. Учебное пособие: Метод учебного пособия считается наиболее полезным для нового пользователя, в котором они проходят через каждый этап выполнения конкретных задач.
      2. Тематический: A тематический подход, когда главы или разделы концентрируются на одной конкретной области интересов, имеет более общее применение для промежуточного пользователя. Некоторые авторы предпочитают излагать свои идеи через статьи, основанные на знаниях, чтобы облегчить потребности пользователей. Этот подход обычно практикуется в динамично развивающейся отрасли, такой как Информационные технологии, где количество пользователей в значительной степени коррелирует с устранением неполадок требованиями
      3. Список или Справочник: Окончательный Тип принципа организации — это тот, при котором команды или задачи просто перечислены в алфавитном порядке или логически сгруппированы, часто с помощью указателей с перекрестными ссылками. Последний подход более полезен для продвинутых пользователей, которые точно знают, какую информацию они ищут.

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

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

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

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

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

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

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

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

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

      1. заинтересовать потенциального пользователя продуктом и внушить ему желание более активно с ним работать.
      2. Информировать его о том, что именно делает продукт, чтобы их ожидания соответствуют тому, что они будут получать.
      3. Чтобы объяснить позицию этого продукта по отношению к другим альтернативам.

      См. также

      • API Writer
      • Сравнение генераторов документации
      • Дизайн по контракту
      • Проектный документ
      • Строка документации
      • Документация
      • Грамотное программирование
      • Файлы README
      • Помощь пользователям
      • Унифицированный язык моделирования UML

      Примечания

      Внешние ссылки

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

      Лекция №18 Документирование ПО

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

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

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

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

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

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

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

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

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

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

      Документация на программу ГОСТ

      Техническая документация на программный продукт (программу) разрабатывается в соответствии с требованиями ГОСТ ЕСПД и её можно разделить на следующие категории:

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

      Различают следующую документацию на программный продукт

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

      Виды эксплуатационной документации и требования к ней

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

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

      Наши специалисты готовы разработать любой документы по требованиям ГОСТ ЕСПД.

      Оформите заявку и задавайте все интересующие вас вопросы по телефону +7(499)755-74-33 e-mail Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра. или через форму заказа.

      Похожие публикации:

      1. Overwolf teamspeak 3 что это
      2. Как вставить картинку в фигуру в powerpoint
      3. Как обновить айфон через компьютер
      4. Как сохранить номер телефона на сим карту xiaomi