Документация по программному обеспечению — это письменный текст или иллюстрация, сопровождающая компьютерное программное обеспечение или встроенная в исходный код. Документация либо объясняет, как работает программное обеспечение, либо как его использовать, и может означать разные вещи для людей, занимающих разные должности.
Документация является важной частью разработки программного обеспечения. К видам документации относятся:
Документация по требованиям — это описание того, что конкретное программное обеспечение делает или должно делать. Он используется на протяжении всей разработки , чтобы сообщить, как функционирует программное обеспечение или как оно должно работать. Он также используется в качестве соглашения или основы соглашения о том, что будет делать программное обеспечение. Требования создаются и потребляются всеми, кто участвует в производстве программного обеспечения, включая: конечных пользователей , клиентов , менеджеров проектов , специалистов по продажам , маркетингу , архитекторов программного обеспечения , инженеров по удобству использования , дизайнеров взаимодействия , разработчиков и тестировщиков .
Требования бывают разных стилей, обозначений и формальностей. Требования могут быть целевыми (например, распределенная рабочая среда ), близкими к проекту (например, сборку можно запустить, щелкнув правой кнопкой мыши файл конфигурации и выбрав функцию «сборка» ) и любыми промежуточными. Их можно определить как утверждения на естественном языке , как нарисованные фигуры, как подробные математические формулы или как их комбинацию.
Разнообразие и сложность документации по требованиям делают ее сложной задачей. Требования могут быть неявными и их трудно обнаружить. Трудно точно знать, сколько и какого рода документации необходимо и сколько можно оставить для архитектурной и проектной документации, а также трудно понять, как документировать требования, учитывая разнообразие людей, которые будут читать и использовать документацию. . Таким образом, документация по требованиям часто бывает неполной (или вообще отсутствует). Без надлежащей документации требований внесение изменений в программное обеспечение становится более трудным и, следовательно, более подверженным ошибкам (снижение качества программного обеспечения ) и отнимает много времени (дорого).
Потребность в документации требований обычно связана со сложностью продукта, влиянием продукта и ожидаемым сроком службы программного обеспечения. Если программное обеспечение очень сложное или разрабатывается многими людьми (например, программное обеспечение для мобильных телефонов), требования могут помочь лучше понять, чего следует достичь. Если программное обеспечение критично с точки зрения безопасности и может оказать негативное влияние на жизнь человека (например, ядерные энергетические системы, медицинское оборудование, механическое оборудование), часто требуется более формальная документация с требованиями. Если ожидается, что программное обеспечение просуществует всего месяц или два (например, очень маленькие приложения для мобильных телефонов, разработанные специально для определенной кампании), может потребоваться очень мало документации по требованиям. Если программное обеспечение представляет собой первую версию, на основе которой позднее была создана документация по требованиям, она очень полезна при управлении изменениями программного обеспечения и проверке того, что в программном обеспечении ничего не было сломано при его модификации.
Традиционно требования указываются в документах с требованиями (например, с использованием текстовых приложений и приложений для работы с электронными таблицами). Для управления возрастающей сложностью и изменяющимся характером документации требований (и документации программного обеспечения в целом) рекомендуются системы, ориентированные на базы данных, и специальные инструменты управления требованиями .
При гибкой разработке программного обеспечения требования часто выражаются в виде пользовательских историй с сопровождающими критериями приемки.
Архитектурная документация (также известная как описание архитектуры программного обеспечения ) — это особый тип проектной документации. В каком-то смысле архитектурные документы являются третьей производной от кода ( проектный документ является второй производной, а кодовые документы — первой). В документах по архитектуре очень мало что относится конкретно к самому коду. Эти документы не описывают, как программировать конкретную программу или даже почему эта конкретная программа существует в той форме, в которой она существует, а вместо этого просто излагают общие требования, которые мотивируют существование такой процедуры. В хорошем архитектурном документе мало подробностей, но много объяснений. Он может предлагать подходы к проектированию нижнего уровня, но оставлять фактические исследования по разведке для других документов.
Другим типом проектного документа является сравнительный документ или торговое исследование. Часто это принимает форму официального документа . Он фокусируется на одном конкретном аспекте системы и предлагает альтернативные подходы. Это может быть уровень пользовательского интерфейса , кода, дизайна или даже архитектуры. В нем будет обрисована ситуация, описана одна или несколько альтернатив и перечислены плюсы и минусы каждой из них. Хороший документ по торговому исследованию насыщен исследованиями, ясно выражает свою идею (без сильной зависимости от тупого жаргона , способного ослепить читателя) и, что наиболее важно, является беспристрастным. Он должен честно и ясно объяснить стоимость любого решения, которое оно предлагает, как наилучшего. Целью исследования торговли является разработка наилучшего решения, а не продвижение определенной точки зрения. Вполне приемлемо не делать никаких выводов или заключить, что ни одна из альтернатив не является достаточно лучшей, чем базовая линия, чтобы оправдать изменение. К этому следует подходить как к научной деятельности, а не как к маркетинговому методу.
Очень важной частью проектного документа при разработке корпоративного программного обеспечения является документ проекта базы данных (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] Однако существует три основных способа организации пользовательской документации.
Пользователи часто жалуются на документацию к программному обеспечению, что только один из этих трех подходов был практически исключен из двух других. Обычно предоставляемая документация по программному обеспечению для персональных компьютеров ограничивается онлайн -справкой , которая дает только справочную информацию о командах или пунктах меню. Работа по обучению новых пользователей или оказанию помощи более опытным пользователям в получении максимальной отдачи от программы возложена на частных издателей, которым разработчик программного обеспечения часто оказывает значительную помощь.
Как и другие формы технической документации, хорошая пользовательская документация выигрывает от организованного процесса разработки. В случае пользовательской документации процесс, как это обычно происходит в промышленности, состоит из пяти этапов: [5]
Для многих приложений необходимо иметь рекламные материалы, чтобы побудить случайных наблюдателей потратить больше времени на изучение продукта. Эта форма документации преследует три цели:
«Сопротивление документации среди разработчиков хорошо известно и не требует особого внимания». [10] Эта ситуация особенно распространена при гибкой разработке программного обеспечения, поскольку эти методологии стараются избегать любых ненужных действий, которые не приносят прямой пользы. В частности, Agile Manifesto выступает за то, чтобы ценить «работающее программное обеспечение выше подробной документации», что можно цинично интерпретировать как «Мы хотим тратить все свое время на программирование. Помните, настоящие программисты не пишут документацию». [11]
Однако опрос среди экспертов по разработке программного обеспечения показал, что документация ни в коем случае не считается ненужной в гибкой разработке. Тем не менее, признается, что существуют мотивационные проблемы в разработке и что могут потребоваться методы документирования, адаптированные к гибкой разработке (например, с помощью систем репутации и геймификации ). [12] [13]