Документация по программному обеспечению — это письменный текст или иллюстрация, которая сопровождает компьютерное программное обеспечение или встроена в исходный код. Документация либо объясняет, как работает программное обеспечение, либо как его использовать, и может означать разные вещи для людей в разных ролях.
Документация является важной частью разработки программного обеспечения. Типы документации включают:
Документация по требованиям — это описание того, что конкретное программное обеспечение делает или должно делать. Она используется на протяжении всей разработки для сообщения о том, как функционирует программное обеспечение или как оно должно работать. Она также используется в качестве соглашения или основы для соглашения о том, что программное обеспечение будет делать. Требования создаются и используются всеми, кто участвует в производстве программного обеспечения, включая: конечных пользователей , клиентов , менеджеров проектов , отдел продаж , маркетинг , архитекторов программного обеспечения , инженеров по удобству использования , проектировщиков взаимодействия , разработчиков и тестировщиков .
Требования могут быть разных стилей, нотаций и формальностей. Требования могут быть целеподобными (например, распределенная рабочая среда ), близкими к дизайну (например, сборки можно запустить, щелкнув правой кнопкой мыши файл конфигурации и выбрав функцию «сборка» ) и чем-то средним. Они могут быть указаны как утверждения на естественном языке , как нарисованные фигуры, как подробные математические формулы или как комбинация всего этого.
Разнообразие и сложность документации по требованиям делают ее проверенной проблемой. Требования могут быть неявными и сложными для раскрытия. Трудно точно знать, сколько и какого рода документации необходимо, а сколько можно оставить для документации по архитектуре и проектированию, и трудно знать, как документировать требования, учитывая разнообразие людей, которые будут читать и использовать документацию. Таким образом, документация по требованиям часто бывает неполной (или отсутствует). Без надлежащей документации по требованиям изменения программного обеспечения становятся более сложными — и, следовательно, более подверженными ошибкам (снижение качества программного обеспечения ) и требующими много времени (дорого).
Необходимость документации по требованиям обычно связана со сложностью продукта, его влиянием и ожидаемым сроком службы программного обеспечения. Если программное обеспечение очень сложное или разрабатывается многими людьми (например, программное обеспечение для мобильных телефонов), требования могут помочь лучше объяснить, чего следует достичь. Если программное обеспечение критично для безопасности и может оказать негативное влияние на жизнь человека (например, ядерные энергетические системы, медицинское оборудование, механическое оборудование), часто требуется более формальная документация по требованиям. Если программное обеспечение, как ожидается, будет существовать всего месяц или два (например, очень маленькие приложения для мобильных телефонов, разработанные специально для определенной кампании), может потребоваться очень мало документации по требованиям. Если программное обеспечение является первым релизом, на основе которого впоследствии будут дорабатываться, документация по требованиям очень полезна при управлении изменением программного обеспечения и проверке того, что в программном обеспечении ничего не было сломано при его изменении.
Традиционно требования указываются в документах по требованиям (например, с использованием приложений для обработки текстов и электронных таблиц). Для управления возросшей сложностью и изменяющимся характером документации по требованиям (и документации по программному обеспечению в целом) рекомендуются системы, ориентированные на базы данных, и специальные инструменты управления требованиями .
В Agile-разработке ПО требования часто выражаются в виде пользовательских историй с соответствующими критериями приемки. Пользовательские истории обычно являются частью функции или эпика, который представляет собой более широкую функциональность или набор связанных функций, которые предоставляют пользователю определенную ценность на основе бизнес-требований.
Архитектурная документация (также известная как описание архитектуры программного обеспечения ) — это особый тип проектной документации. В некотором смысле архитектурные документы являются третьей производной от кода ( проектная документация является второй производной, а документы кода — первой). Очень мало в архитектурных документах относится к самому коду. Эти документы не описывают, как программировать определенную процедуру, или даже почему эта конкретная процедура существует в той форме, в которой она существует, а вместо этого просто излагают общие требования, которые мотивируют существование такой процедуры. Хороший архитектурный документ содержит мало подробностей, но много объяснений. Он может предлагать подходы для проектирования более низкого уровня, но оставить фактические исследования по разведке для других документов.
Другой тип проектного документа — сравнительный документ или торговое исследование. Часто он принимает форму технического документа . Он фокусируется на одном конкретном аспекте системы и предлагает альтернативные подходы. Это может быть на уровне пользовательского интерфейса , кода, дизайна или даже архитектуры. Он обрисует ситуацию, опишет одну или несколько альтернатив и перечислит плюсы и минусы каждой из них. Хороший документ торгового исследования содержит много исследований, четко выражает свою идею (не полагаясь на тупой жаргон , чтобы ослепить читателя), и, что самое важное, является беспристрастным. Он должен честно и ясно объяснять стоимость любого решения, которое он предлагает как лучшее. Цель торгового исследования — разработать лучшее решение, а не навязывать определенную точку зрения. Вполне приемлемо не делать никаких выводов или заключить, что ни одна из альтернатив не является достаточно лучшей, чем базовая линия, чтобы оправдать изменение. К нему следует подходить как к научному начинанию, а не как к маркетинговому приему.
Очень важной частью проектного документа в разработке корпоративного программного обеспечения является документ проектирования базы данных (DDD). Он содержит концептуальные, логические и физические элементы проектирования. DDD включает формальную информацию, которая нужна людям, взаимодействующим с базой данных. Целью его подготовки является создание общего источника для использования всеми игроками на сцене. Потенциальными пользователями являются:
Если говорить о системах реляционных баз данных , документ должен включать следующие части:
Очень важно включить всю информацию, которая будет использоваться всеми актерами в сцене. Также очень важно обновлять документы, поскольку любые изменения происходят и в базе данных.
Важно, чтобы документы кода, связанные с исходным кодом (которые могут включать файлы README и документацию API ), были подробными, но не настолько многословными, чтобы их поддержка стала слишком трудоемкой или сложной. Различные руководства по документации и обзоры обычно встречаются в отношении программного приложения или программного продукта, документируемого авторами API . Эта документация может использоваться разработчиками, тестировщиками, а также конечными пользователями. Сегодня множество высокопроизводительных приложений можно увидеть в областях энергетики, транспорта, сетей, аэрокосмической промышленности, безопасности, промышленной автоматизации и в ряде других областей. Техническая документация стала важной в таких организациях, поскольку базовый и продвинутый уровень информации могут меняться с течением времени вместе с изменениями архитектуры. Есть доказательства того, что наличие хорошей документации кода фактически снижает затраты на обслуживание программного обеспечения. [1]
Документы с кодом часто организованы в виде справочного руководства , что позволяет программисту быстро находить произвольную функцию или класс.
Часто такие инструменты , как Doxygen , NDoc , Visual Expert , Javadoc , JSDoc , EiffelStudio , Sandcastle , ROBODoc , POD , TwinText или Universal Report, можно использовать для автоматической генерации документов кода, то есть они извлекают комментарии и программные контракты (если таковые имеются) из исходного кода и создают справочные руководства в таких формах, как текстовые или HTML- файлы.
Идея автоматической генерации документации привлекательна для программистов по разным причинам. Например, поскольку она извлекается из самого исходного кода (например, через комментарии ), программист может писать ее, ссылаясь на код, и использовать те же инструменты, которые использовались для создания исходного кода, для создания документации. Это значительно упрощает поддержание актуальности документации.
Возможным недостатком является то, что только программисты могут редактировать этот тип документации, и от них зависит обновление вывода (например, запуск задания cron для обновления документов каждую ночь). Некоторые охарактеризовали бы это как плюс, а не минус.
Уважаемый ученый-компьютерщик Дональд Кнут отметил, что документирование может быть очень сложным процессом, требующим запоздалой мысли, и выступил за грамотное программирование , написанное в то же время и в том же месте, что и исходный код , и извлеченное автоматическими средствами. Языки программирования Haskell и CoffeeScript имеют встроенную поддержку простой формы грамотного программирования, но эта поддержка не получила широкого распространения.
Разъяснительное программирование является результатом практического применения грамотного программирования в реальных контекстах программирования. Разъяснительная парадигма предполагает, что исходный код и документация должны храниться отдельно.
Часто разработчикам программного обеспечения необходимо иметь возможность создавать и получать доступ к информации, которая не будет частью исходного файла. Такие аннотации обычно являются частью нескольких видов деятельности по разработке программного обеспечения, таких как обход кода и портирование, где сторонний исходный код анализируется функциональным способом. Таким образом, аннотации могут помочь разработчику на любом этапе разработки программного обеспечения, где формальная система документации будет препятствовать прогрессу.
В отличие от документов кода, пользовательские документы просто описывают, как используется программа.
В случае библиотеки программного обеспечения документы кода и пользовательские документы в некоторых случаях могут быть фактически эквивалентны и их стоит объединить, но для общего приложения это не всегда так.
Обычно пользовательская документация описывает каждую функцию программы и помогает пользователю в реализации этих функций. Очень важно, чтобы пользовательские документы не были запутанными и чтобы они были актуальными. Пользовательские документы не должны быть организованы каким-либо определенным образом, но очень важно, чтобы у них был подробный индекс . Последовательность и простота также очень ценны. Пользовательская документация считается контрактом, определяющим, что будет делать программное обеспечение. API Writers очень хорошо справляются с написанием хороших пользовательских документов, поскольку они хорошо знают архитектуру программного обеспечения и используемые методы программирования. См. также техническое письмо .
Пользовательская документация может быть создана в различных онлайн-форматах и печатных форматах. [2] Однако существует три основных способа организации пользовательской документации.
Распространенной жалобой пользователей на документацию программного обеспечения является то, что был использован только один из этих трех подходов, что практически исключило два других. Обычно документацию программного обеспечения для персональных компьютеров ограничивают онлайн -справкой , которая дает только справочную информацию о командах или пунктах меню. Работа по обучению новых пользователей или помощь более опытным пользователям в максимальном использовании программы возлагается на частных издателей, которым часто оказывает значительную помощь разработчик программного обеспечения.
Как и другие формы технической документации, хорошая пользовательская документация выигрывает от организованного процесса разработки. В случае пользовательской документации процесс, как это обычно происходит в промышленности, состоит из пяти шагов: [5]
Для многих приложений необходимо иметь некоторые рекламные материалы, чтобы побудить случайных наблюдателей тратить больше времени на изучение продукта. Эта форма документации имеет три цели:
«Сопротивление документации среди разработчиков хорошо известно и не нуждается в подчеркивании». [10] Эта ситуация особенно распространена в гибкой разработке программного обеспечения, поскольку эти методологии пытаются избегать любых ненужных действий, которые не приносят прямой ценности. В частности, Agile Manifesto пропагандирует ценность «работающего программного обеспечения вместо исчерпывающей документации», что можно цинично интерпретировать как «Мы хотим тратить все наше время на кодирование. Помните, настоящие программисты не пишут документацию». [11]
Однако опрос среди экспертов по программной инженерии показал, что документация ни в коем случае не считается ненужной в гибкой разработке. Тем не менее, признается, что в разработке есть мотивационные проблемы, и что могут потребоваться методы документирования, адаптированные к гибкой разработке (например, через системы репутации и геймификацию ). [12] [13]
Docs as Code — это подход к документации, который относится к ней с той же строгостью и процессами, что и к программному коду. Это включает: