Документация на программное обеспечение — печатные руководства пользователя, диалоговая (оперативная) документация и справочный текст, описывающие, как пользоваться программным продуктом.
Документ — элемент документации: целевая информация, предназначенная для конкретной аудитории, размещенная на конкретном носителе (например, в книге, на диске, в краткой справочной карте) в заданном формате.
Программный документ — документ, содержащий в зависимости от назначения данные, необходимые для разработки, производства, эксплуатации, сопровождения программы или программного средства.
Типы документации
Существует четыре основных типа документации на ПО:
- архитектурная/проектная — обзор программного обеспечения, включающий описание рабочей среды и принципов, которые должны быть использованы при создании ПО
- техническая — документация на код, алгоритмы, интерфейсы, API
- пользовательская — руководства для конечных пользователей,
- администраторов системы и другого персонала
- маркетинговая
Архитектурная/проектная документация
Проектная документация обычно описывает продукт в общих чертах. Не описывая того, как что-либо будет использоваться, она скорее отвечает на вопрос «почему именно так». Например, в проектном документе программист может описать обоснование того, почему структуры данных организованы именно таким образом. Описываются причины, почему какой-либо класс сконструирован определённым образом, выделяются паттерны, в некоторых случаях даже даются идеи, как можно будет выполнить улучшения в дальнейшем. Ничего из этого не входит в техническую или пользовательскую документацию, но всё это действительно важно для проекта.
Как начать работать с программой «АЛТИУС – Исполнительная документация»
Техническая документация
При создании программы, одного лишь кода, как правило, недостаточно. Должен быть предоставлен некоторый текст, описывающий различные аспекты того, что именно делает код. Такая документация часто включается непосредственно в исходный код или предоставляется вместе с ним. Подобная документация имеет сильно выраженный технический характер и в основном используется для определения и описания API, структур данных и алгоритмов.
Часто при составлении технической документации используются автоматизированные средства — генераторы документации, такие как Doxygen, javadoc, NDoc и другие. Они получают информацию из специальным образом оформленных комментариев в исходном коде, и создают справочные руководства в каком-либо формате, например, в виде текста или HTML.
Использование генераторов документации и документирующих комментариев многими программистами признаётся удобным средством, по различным причинам. В частности, при таком подходе документация является частью исходного кода, и одни и те же инструменты могут использоваться для сборки программы и одновременной сборки документации к ней. Это также упрощает поддержку документации в актуальном состоянии.
Пользовательская документация
В отличие от технической документации, сфокусированной на коде и том, как он работает, пользовательская документация описывает лишь то, как использовать программу.
Почему техническая документация — это интересно
В случае если продуктом является программная библиотека, пользовательская документация и документация на код становятся очень близкими, почти эквивалентными понятиями. Но в общем случае, это не так. Обычно, пользовательская документация представляет собой руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идёт ещё дальше и предоставляет
инструкции о том, что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение. Существует три подхода к организации пользовательской документации.
Вводное руководство (англ. tutorial), наиболее полезное для новых пользователей, последовательно проводит по ряду шагов, служащих для выполнения каких-либо типичных задач. Тематический подход, при котором каждая глава руководства посвящена какой-то отдельной теме, больше подходит для совершенствующихся пользователей. В последнем, третьем подходе, команды или задачи организованы в виде алфавитного справочника — часто это хорошо воспринимается продвинутыми пользователями, хорошо знающими, что они ищут. Жалобы пользователей обычно относятся к тому, что документация охватывает только один из этих подходов, и поэтому хорошо подходит лишь для одного класса пользователей.
Во многих случаях разработчики программного продукта ограничивают набор пользовательской документации лишь встроенной системой помощи (англ. online help), содержащей справочную информацию о командах или пунктах меню. Работа по обучению новых пользователей и поддержке совершенствующихся пользователей перекладывается на частных издателей, часто оказывающих значительную помощь разработчикам.
Маркетинговая документация
Для многих приложений необходимо располагать рядом с ними рекламные материалы, с тем, чтобы заинтересовать людей, обратив их внимание на продукт. Такая форма документации имеет целью:
- подогреть интерес к продукту у потенциальных пользователей
- информировать их о том, что именно делает продукт, с тем, чтобы их ожидания совпадали с тем, что они получат
- объяснить положение продукта по сравнению с конкурирующими решениями
Одна из хороших маркетинговых практик — предоставление слогана, простой запоминающейся фразы, иллюстрирующей то, что мы хотим донести до пользователя, а также характеризующей ощущение, которое создаёт продукт.
Часто бывает так, что коробка продукта и другие маркетинговые материалы дают более ясную картину о возможностях и способах использования программы, чем всё остальное.
Источник: unetway.com
Кто составляет и поддерживает документацию к коду и как часто она обновляется в проекте
Вопрос. Кто составляет и поддерживает документацию к коду и как часто она вообще обновляется в самом проекте?
Ответ. Если к примеру разрабатывает только разработчик, то он ее и поддерживает. Яркие примеры различных программ, библиотек и компонентов в github’e. Либо может поддерживать сообщество людей, если это крупное open source решение.
Если говорим конкретно про детали реализации, то в основном этим занимаются разработчики. Так как они пишут и поддерживают этот самый код. И порой лучше них никто в компании может и не знать его. Все остальные руководства пишут уже другие люди внутри компании, если они есть.
К примеру, технические писатели. Они как раз занимаются составлением различной технической документацией, которая будет понятна пользователю. Руководство пользователя, руководство по эксплуатации, руководство для внедрения и тд.
Лично я считаю, что люди в данной должности так же могут писать и документацию к коду. В таком случае есть минус — это придется часто отвлекать разработчиков от их работы, чтобы они объяснили какие-то вещи. Что, как и почему это происходит.
Документацию основном обновляют когда появляется новый функционал, который нужно задокументировать, как для пользователей, так и для других разработчиков.
Но как показывается практика и общение с другими разработчиками — не всегда удается составить документацию на должном уровне. Либо она вообще отсутствует, либо содержит много неактуальной информации. Для того чтобы разработчикам вести документацию, нужно выделять время для этого, освобождая их от задач. И помимо всего этого, у руководства компании должно быть четкое понимание, что документация к проекту нужна.
К примеру, когда я с командой работают над проектом, то выделяем время на ведение документации. Хотим мы этого или нет. Используя для этого GitLab. И такой системный подход окупается с лихвой после завершения самого проекта, его дальнейшая поддержка, ввод новых участников или других исполнителей в проект.
Антон Чураков
Автор публикации Об авторе
Получил образование по специальности «Информационные системы (по отраслям)». Работал программистом в компании, занимающейся разработкой и внедрением системы BPM для автоматизации бизнес-процессов. Опыт работы разработчким ПО с 2016 года по направлениям PHP/Laravel и .NET
Журнал Цифрового Волка — Статьи о технической разработке ИТ-проектов. Как проектируем, разрабатываем, запускаем и решаем проблемы между разработкой и бизнес-задачами. От разработчиков разработчикам..
Источник: digitalwolf.org
Вопросы по программной документации
Определённых требований к выпуску этого документа не предъявляется. Он может быть выпущен как на бумажном носителе, так и на оптическом носителе данных. На практике (особенно при большом объеме текста программы) чаще выпускается в электронном виде или комбинированном — есть удостоверяющий лист с названием и ТП записанный на диск, в спецификации делается запись, что ТП на оптическом носителе данных.
Как определить порядок подписания, согласования и утверждения Пояснительной записки к ПО?
Документ «Пояснительная записка», выполненный по ГОСТ 19.404-79, должен быть согласован и утверждён вместе с остальными документами, входящими в состав рабочего проекта, т. е. до начала приёмочных испытаний.
Заказчик требует наряду с разработкой ТЗ на изделие разработать ТЗ на программное обеспечение. Зачем нужен такой документ? Какая информация должна быть в нём указана?
ТЗ на изделие в целом определяет основные направления разработки: состава, конструкции и принципа работы, а также обосновывает технические и технико-экономические характеристики. ТЗ на программное обеспечение изделия позволит установить и конкретизировать требования непосредственно к программному продукту, выработанные на основе требований основного ТЗ. ТЗ на программные изделия обычно содержит сведения о назначении и области применения ПО, технические, технико-экономические и специальные требования, стадии и сроки разработки, виды испытаний. Полная информация о требованиях к содержанию разделов и оформлению ТЗ на разработку программы или программного изделия приведена в ГОСТ 19.201-78.
В техническом задании на ОКР есть требование: «Комплект программной документации на программное обеспечение из состава изделия должен быть разработан в соответствии с требованиями ГОСТ 19.101-77». Что это означает?
Чем отличаются программные документы «Руководство программиста» и «Руководство системного программиста»?
Документ «Руководство программиста» содержит сведения, необходимые для эксплуатации программы: назначение, условия применения, способ обращения к программе, входные и выходные данные. В документе «Руководство системного программиста» содержатся сведения, необходимые для настройки, проверки и обеспечения функционирования программы.
Какие документы обязательно должны быть разработаны для программных комплексов, какие – для программных компонентов?
В соответствии с требованиями ГОСТ 19.101-77, обязательным документом для программного комплекса является спецификация, для программного компонента – текст программы. Если предполагается, что компонент может иметь самостоятельное применение, для него также обязательным документом является спецификация.
Что такое программное изделие?
В соответствии с ГОСТ 19.004 программное изделие – это «Программа на носителе данных, являющаяся продуктом промышленного производства».
Также читайте нашу статью «Программная документация и ее разновидности»
Источник: tehpis.ru