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

редактировать
Объясняет функциональные возможности программного обеспечения

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

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

  • Требования - утверждения, которые идентифицируют атрибуты, возможности, характеристики или качества системы. Это основа того, что будет или было реализовано.
  • Архитектура / Дизайн - Обзор программного обеспечения. Включает отношения к среде и принципы построения, которые будут использоваться при проектировании компонентов программного обеспечения.
  • Технические - Документация кода, алгоритмов, интерфейсов и API.
  • Конечный пользователь - Руководства для конечный пользователь, системные администраторы и вспомогательный персонал.
  • Маркетинг - Как продвигать продукт и анализ рыночного спроса.
Содержание
  • 1 Документация по требованиям
  • 2 Документация по проектированию архитектуры
  • 3 Техническая документация
    • 3.1 Техническая документация, встроенная в исходный код
      • 3.1.1 Грамотное программирование
      • 3.1.2 Разъяснительное программирование
  • 4 Пользовательская документация
    • 4.1 Составление пользовательской документации
  • 5 Документация и гибкая разработка противоречие
  • 6 Маркетинговая документация
  • 7 См. также
  • 8 Примечания
  • 9 Внешние ссылки
Документация по требованиям

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

Требования бывают разных стилей, обозначений и формальностей. Требования могут быть целевыми (например, распределенная рабочая среда), близкими к дизайну (например, сборки могут быть запущены, щелкнув правой кнопкой мыши файл конфигурации и выбрав функцию «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. Чтобы объяснить позицию этого продукта по отношению к другим альтернативам.
См. также
Примечания
Внешние ссылки
Последняя правка сделана 2021-06-08 08:27:10
Содержание доступно по лицензии CC BY-SA 3.0 (если не указано иное).
Обратная связь: support@alphapedia.ru
Соглашение
О проекте