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

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

  • автор:

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

Документа́ция на программное обеспечение — печатные руководства пользователя, диалоговая (оперативная) документация и справочный текст, описывающие, как пользоваться программным продуктом [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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Что такое эксплуатационная документация?

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

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

Какие основные документы входят в состав эксплуатационной документации?

  • руководство пользователя;
  • руководствоадминистратора;
  • руководствопрограммиста;
  • и т.д.

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

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

  • ЕСКД, Единая система конструкторской документации (ГОСТ 2);
  • ЕСПД, Единая система программной документации (ГОСТ 19);
  • КСАС, Комплекс стандартов на автоматизированные системы (ГОСТ
    34).

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

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

Данный вид документации в плоскости зарубежных стандартов разработки документации соответствует следующим видам:

  • End user, руководства для пользователей, администраторов и обслуживающего персонала (аналог Руководство пользователя, Руководство администратора);
  • Technical, описание кода, алгоритмов и интерфейсов (аналог Руководство программиста, Справочник разработчика).

В отличие от ГОСТов, за рубежом изначально несколько иной подход к стандартам документирования.

Где найти примеры эксплуатационной документации?

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

Сколько стоит разработка эксплуатационной документации?

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

Как заказать разработку эксплуатационной документации?

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

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

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

Виды документации для программного обеспечения

В соответствии с таким определением, техническая документация по ПО состоит из четырёх основных типов:

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

• Техническая – алгоритмы, код, интерфейсы, АРI.

• Пользовательская – руководства для пользователей программы.

• Маркетинговая – содержащая рекламную информацию о продукте.

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

Техническая документация (все указанные виды которой можно заказать в компании «ТехРайтКонсалт»). не только указывает конкретные коды. Она, как правило, также описывает различные аспекты того, что этот код делает. Она имеет явно выраженный технический характер и используется в основном для описания и определения API, алгоритмов и структур данных. При её составлении возможно использование генераторов документации (Doxygen, NDoc, javadoc и др.), что даёт возможность постоянно поддерживать такую документацию в актуальном состоянии. В последнем случае техническая документация является частью исходного кода. Тогда одни и те же инструменты можно использовать как для сборки программы, так и для сборки в то же время документации к ней.

Хорошая пользовательская документация состоит из:

• вводного руководства, где рассматриваются общие вопросы выполнения типичных задач;

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

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

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

Стандарты для разработки ПО

Основой для создания любой документации на программные продукты служат стандарты.

Современных стандартов по разработке технической документации для программного обеспечения в Российской Федерации до сих пор нету ещё со времён СССР. Хотя стандарты и модернизируются. Последнее обновление ГОСТ 2.015-2013.

В таких условиях IT-компании вопрос разработки документации для программного обеспечения решают по-разному. Одни пытаются копировать и внедрять западные стандарты. Другие – использовать отечественные. Третьи – создают свои собственные.

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

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

• Какова нормативная база и как её следует применять?

• Какая именно документация нужна среди огромного количества документов?

Остановимся на этих вопросах подробнее.

В настоящее время действуют следующие стандарты документирования:

ГОСТ 19.201 ( Единая система программной документации (ЕСПД);

ГОСТ 2.015-2013 (Единая система конструкторской документации (ЕСКД);

ГОСТ 34.602 (Комплекс стандартов на автоматизированные системы (КСАС).

Указанные стандарты с 2006 года применять не обязательно. В соответствии с нормами Федерального закона № 184-ФЗ «О техническом регулировании» вместо стандартов применяются специально разработанные технические регламенты. Но ГОСТы по-прежнему нужно применять при разработке документации для государственных заказчиков, а также для крупных организаций (особенно с государственным участием). Последние, как правило, разрабатывают собственные стандарты на основе указанных ГОСТов.

Следует также помнить, что в соответствии с ФЗ «О техническом регулировании» национальные стандарты имеют всегда приоритет над международными. То есть, использовать международные стандарты можно лишь в случаях, если последние не противоречат национальным! Благо, свободы действий отечественные стандарты предоставляют намного больше зарубежных. Последние пересматриваются каждые 5-7 лет и характеризуются большей конкретизацией, но отображают весь актуальный опыт за указанный период времени. Отечественные же (не имея столь разработанной конкретики) характеризуются глубокой разработкой концептуальных моментов. Это позволяет создавать на их основе неплохие стандарты в соответствии с требованиями времени.

Техническое задание

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

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

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

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

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

Автор: Администрация

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

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

Ваш адрес email не будет опубликован. Обязательные поля помечены *