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

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

Документи́рование — это важная часть в разработке программного обеспечения, но часто ей уделяется недостаточно внимания.

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

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

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

техническая — документация на код, алгоритмы, интерфейсы, API

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

маркетинговая

[править]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

объяснить положение продукта по сравнению с конкурирующими решениями

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

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

Основные понятия САПР-функциональное и системное наполнение

Система автоматизации проектных работ (САПР) или CAD(англ. Computer-Aided Design) — программный пакет, предназначенный для проектирования (разработки) объектов производства (или строительства), а также оформления конструкторской и/или технологической документации.

Современные САПР (CAD) используются совместно с системами автоматизации инженерных расчётов и анализа CAE (Computer-aided engineering). Некоторые САПР содержат интегрированные средства автоматизации инженерных расчётов и анализа.

Данные из CAD-систем передаются в CAM (англ. Computer-aided manufacturing — система автоматизированной разработки программ обработки деталей для станков с ЧПУ или ГАПС (Гибких автоматизированных производственных систем)).

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

Следует отметить, что русский термин «САПР» по отношению к промышленным системам имеет более широкое толкование, чем CAD — он включает в себя CAD, CAM и CAE.

Компоненты САПР

Выделяют следующие виды обеспечения:

математическое обеспечение САПР — математические модели, методики и способы их получения;

лингвистическое обеспечение САПР;

техническое обеспечение САПР — устройства ввода, обработки и вывода данных, средства поддержки архива проектных решений, устройства передачи данных;

информационное обеспечение САПР — информационная база САПР, автоматизированные банки данных, системы управления базами данных (СУБД);

программное обеспечение САПР;

программные компоненты САПР (примером может служить Геометрический решатель САПР);

методическое обеспечение;

организационное обеспечение.

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

коллективная работа в сети;

экспорт — импорт файлов различных форматов;

масштабирование объектов;

группировка объектов, передвижение, растяжка, поворот, разрезание, изменение размеров, работа со слоями;

перерисовка;

управление файлами;

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

работа с цветом;

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

Примерами пакетов этого класса являются: AutoCAD (Autodesk), DesignCAD, Grafic CAD Professional, DrawBase, MicroStation (Bentley Systems), TurboCAD.