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

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

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

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

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

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

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

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

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

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

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

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

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

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

Когда мы говорим о Реляционная база данных Системы, документ должен включать следующие части:

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

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

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

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

Это важно для документов кода, связанных с исходным кодом (которые могут включать ПРОЧТИ МЕНЯ файлы и API документация), чтобы быть исчерпывающим, но не настолько многословным, чтобы их обслуживание становилось слишком трудоемким или сложным. Различные практические и обзорные руководства по документации обычно можно найти для конкретного программного приложения или программного продукта, документируемого Авторы API. Эта документация может быть использована разработчиками, тестировщиками, а также конечными пользователями. Сегодня множество высокопроизводительных приложений можно увидеть в сферах энергетики, транспорта, сетей, аэрокосмической промышленности, безопасности, промышленной автоматизации и во многих других областях. Техническая документация стала важной в таких организациях, поскольку базовый и расширенный уровень информации может меняться с течением времени с изменениями архитектуры.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Руководство: А руководство Подход считается наиболее полезным для нового пользователя, в котором они проходят через каждый шаг выполнения конкретных задач.[2]
  2. Тематические: А тематический Подход, при котором главы или разделы сосредоточены на одной конкретной интересующей области, является более общим для промежуточного пользователя. Некоторые авторы предпочитают выражать свои идеи через статьи, основанные на знаниях, чтобы облегчить потребности пользователей. Такой подход обычно практикуется в динамично развивающейся отрасли, например в Информационные технологии, где количество пользователей в значительной степени коррелирует с исправление проблем требования [3]
  3. Список или ссылка: Последний тип принципа организации - это тот, в котором команды или задачи просто перечислены в алфавитном порядке или логически сгруппированы, часто с помощью указателей с перекрестными ссылками. Этот последний подход более полезен для опытных пользователей, которые точно знают, какую информацию они ищут.

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

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

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

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

Документация и полемика по гибкой разработке

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

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

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

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

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

Смотрите также

Примечания

  1. ^ RH Earle, MA Rosso, KE Alexander (2015) Пользовательские предпочтения жанров программной документации. Материалы 33-й ежегодной международной конференции по дизайну коммуникации (ACM SIGDOC).
  2. ^ Woelz, Карлос. "Учебник по документации KDE". Получено 15 июн 2009.
  3. ^ Microsoft. «Статьи базы знаний по разработке драйверов». Получено 15 июн 2009.
  4. ^ Томас Т. Баркер, Написание программной документации, Предисловие, xxiv. Часть Аллин и Бэкон Серия технических коммуникаций, 2-е изд. Верхняя река Сэдл: Pearson Education, 2003. ISBN  0321103289 В архиве 13 мая 2013 г. Wayback Machine
  5. ^ Баркер, стр. 118.
  6. ^ Баркер, стр. 173.
  7. ^ Баркер, стр. 217.
  8. ^ Баркер, стр. 240.
  9. ^ Хербслеб, Джеймс Д. и Мойтра, Депендра. В: Программное обеспечение IEEE, т. 18, нет. 2, стр. 16-20, март / апрель 2001 г.
  10. ^ Ракитин, Стивен. , «Манифест вызывает цинизм». IEEE Computer, т. 34, нет. 12, стр. 4 января 2001 г.
  11. ^ Праузе, Кристиан Р. и Зоя Дурдик. «Архитектурное проектирование и документация: отходы в гибкой разработке?» В: Международная конференция по программному обеспечению и системным процессам (ICSSP), IEEE, 2012.
  12. ^ Селик, Бран. «Кто-нибудь из Agile-документации?» В: Программное обеспечение IEEE, т. 26, вып. 6. С. 11-12, 2009.

внешняя ссылка