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

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

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

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

Типы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Разъясняющее программирование

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Документы как код

«Документация как код» — это подход к документации, при котором к ней относятся с такой же строгостью и процессами, как и к программному коду. Это включает в себя:

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

Преимущества документов как кода:

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

Настройка контроля версий . Начните с размещения документации в системе контроля версий. Структурируйте его аналогично вашей кодовой базе.
Автоматизация процессов : внедрение инструментов CI/CD для автоматизации создания и развертывания документации.
Определите роли : назначьте роли и обязанности по документации в команде Agile. Убедитесь, что все понимают важность документации.
Регулярные проверки . Запланируйте регулярные проверки документации в рамках ретроспектив спринта.

См. также

Примечания

^ «Как получить бюджет на документацию кода» .
^ «Р. Х. Эрл, М. А. Россо, К. Е. Александр (2015) Предпочтения пользователей в жанрах документации по программному обеспечению. Материалы 33-й ежегодной международной конференции по проектированию коммуникаций (ACM SIGDOC)» .
^ Вельц, Карлос. «Букварь документации KDE» . Проверено 15 июня 2009 г.
^ Майкрософт . «Статьи базы знаний по разработке драйверов» . Майкрософт . Проверено 15 июня 2009 г.
^ Томас Т. Баркер, Написание документации по программному обеспечению , Предисловие, xxiv. Часть серии Allyn & Bacon по техническим коммуникациям, 2-е изд. Река Аппер-Седл : Pearson Education , 2003. ISBN 0321103289 Архивировано 13 мая 2013 г. в Wayback Machine.
^ Баркер, стр. 118.
^ Баркер, стр. 173.
^ Баркер, стр. 217.
^ Баркер, стр. 240.
^ Хербслеб, Джеймс Д. и Мойтра, Депендра. В: Программное обеспечение IEEE , вып. 18, нет. 2, стр. 16–20, март/апрель 2001 г.
^ Ракитин, Стивен. « Манифест порождает цинизм». IEEE Компьютер, том. 34, нет. 12, с. 4, 2001 г.
^ Прауз, Кристиан Р. и Зоя Дурдик. «Архитектурное проектирование и документация: потери в гибкой разработке?» В: Международная конференция по программному обеспечению и системным процессам (ICSSP), IEEE, 2012.
^ Селич, Бран. «Гибкая документация, кто-нибудь?» В: Программное обеспечение IEEE , вып. 26, нет. 6, стр. 11-12, 2009 г.

[1] «Как получить бюджет на документацию кода» .

[2] «Р. Х. Эрл, М. А. Россо, К. Е. Александр (2015) Предпочтения пользователей в жанрах документации по программному обеспечению. Материалы 33-й ежегодной международной конференции по проектированию коммуникаций (ACM SIGDOC)» .

[kdp-3] Вельц, Карлос. «Букварь документации KDE» . Проверено 15 июня 2009 г.

[kbad-4] Майкрософт . «Статьи базы знаний по разработке драйверов» . Майкрософт . Проверено 15 июня 2009 г.

[5] Томас Т. Баркер, Написание документации по программному обеспечению , Предисловие, xxiv. Часть серии Allyn & Bacon по техническим коммуникациям, 2-е изд. Река Аппер-Седл : Pearson Education , 2003. ISBN 0321103289 Архивировано 13 мая 2013 г. в Wayback Machine.

[6] Баркер, стр. 118.

[7] Баркер, стр. 173.

[8] Баркер, стр. 217.

[9] Баркер, стр. 240.

[10] Хербслеб, Джеймс Д. и Мойтра, Депендра. В: Программное обеспечение IEEE , вып. 18, нет. 2, стр. 16–20, март/апрель 2001 г.

[11] Ракитин, Стивен. « Манифест порождает цинизм». IEEE Компьютер, том. 34, нет. 12, с. 4, 2001 г.

[12] Прауз, Кристиан Р. и Зоя Дурдик. «Архитектурное проектирование и документация: потери в гибкой разработке?» В: Международная конференция по программному обеспечению и системным процессам (ICSSP), IEEE, 2012.

[13] Селич, Бран. «Гибкая документация, кто-нибудь?» В: Программное обеспечение IEEE , вып. 26, нет. 6, стр. 11-12, 2009 г.

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]