Что такое документация в программировании
Перейти к содержимому

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

  • автор:

Техническая документация – что это такое, какой она должна быть и кто ее создает?

Андрей Андреев

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

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

Что такое техническая документация на ПО? Ее виды и форматы

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

Подготовка документации на программное обеспечение является очень важным этапом процесса его разработки

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

  • Проектная (архитектурная). Описывает основные положения, цели, задачи и этапы проекта, которые применяются при создании программного обеспечения и его рабочей среды. Представляет собой общий обзор ПО, предназначенный, прежде всего, для работающих над проектом специалистов.
  • Техническая. Иногда так называют абсолютно всю документацию для программного обеспечения, хотя это не совсем верно. Непосредственно техдокументация включает описание программного кода и выполняемых им функций, структур данных, алгоритмов, API и интерфейсов. Кроме того, в ней подробно отображается процесс разработки ПО, принцип его действия и порядок эксплуатации. Часто такие материалы поставляются в комплекте с исходным кодом программы или же встраиваются в него в виде комментариев. Для упрощения создания и обновления техдокументов используют специальные шаблоны или делают это автоматизировано при помощи генераторов документации (Javadoc, Doxygen, NDoc и т.д.).
  • Пользовательская. Если первые два вида материалов ориентированы на специалистов, то эта категория предназначена для пользователей программного обеспечения. В ней нет сложных технических описаний кода и принципов его работы, вместо этого она сосредоточена на описании функций ПО и правил его эксплуатации. Среди наиболее распространенных форматов пользовательской документации можно отметить краткое руководство пользователя (User’s Guide) и подробный справочник пользователя (User’s Reference). Также она нередко содержит инструкцию по решению проблем и ответы на часто задаваемые вопросы.
  • Маркетинговая. Еще одним из основных видов документации на ПО являются маркетинговые материалы, которые помогают привлечь внимание целевой аудитории к продукту, рассказать о его предназначении, возможностях и преимуществах. В отличие от пользовательской, маркетинговая документация гораздо более краткая. Часто она состоит из одного рекламного буклета, предназначенного для ознакомления пользователя с программой или приложением.

Какой должна быть качественная документация?

Прежде всего, она должна соответствовать определенному набору стандартов. А именно, таким, как:

  • Структурированность. Наличие четкой структуры является одним из важнейших требований к технической документации. Она должна быть логически упорядочена в разделы и подразделы, иметь абзацы, списки и другие элементы форматирования текста. Если речь идет о пользовательских мануалах, то одним лишь текстовым описанием здесь не обойтись – его нужно дополнять скриншотами программы в высоком качестве. Не менее популярными считаются видео-мануалы, которые, впрочем, не могут полностью заменить собой текстовые материалы.
  • Единообразие. Вся документация на программное обеспечение должна быть оформлена в едином формате, включая как проектные и технические документы для сотрудников, так и материалы для пользователей. Кроме того, в ходе ее составления следует сверяться с другими документами, выпущенными вашей компанией, чтобы придерживаться единого корпоративного стиля. Нелишним также будет заранее стандартизировать процесс подготовки документации, чтобы избежать каких-либо расхождений в дальнейшем.
  • Информативность. Еще одним важным признаком качественной документации на ПО является ее понятность и информативность. Для достижения этой цели нужно уметь соблюсти баланс между объемом данных и простотой их изложения. Ухудшить этот показатель может как недостаток, так и избыток информации, особенно, когда дело касается документации для пользователей. С одной стороны, не нужно делать ее излишне поверхностной и упрощенной, а с другой нельзя допустить чрезмерного усложнения материала.
  • Релевантность. Хорошая техническая документация обязательно должна быть предназначена для определенной целевой аудитории. Создание общего универсального руководства для разработчиков и пользователей – это интересная, но трудновыполнимая задача, которая вряд ли будет под силу даже опытному техрайтеру. Перед разработкой материалов желательно определить круг сотрудников или клиентов, для которых они будут максимально полезны и интересны. Также необходимо иметь представление об уровне подготовки аудитории и о том, какие ее задачи и проблемы сможет решить эта документация.

Что такое техническое задание и технический проект?

Как правило, всю техническую документацию необязательно прописывать до начала разработки программного обеспечения. Чаще всего современные IT-проекты создаются по методологии Agile, а работа над ними ведется по спринтам, что позволяет писать документацию параллельно с процессом разработки.

Свяжите сервисы между собой без программистов за 5 минут!

Подключение Weblium

Подключение Weblium

Как настроить выгрузку новых квизов из QuizGo в Retail CRM?

Как настроить выгрузку новых квизов из QuizGo в Retail CRM?

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

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

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

Говоря простым языком, если техническое задание отвечает на вопрос «что нужно сделать?», то технический проект – на вопрос «как это сделать?».

Кто такой технический писатель? Особенности, задачи и проблемы этой профессии

Разработкой технической документации на программное обеспечение занимается технический писатель (technical writer, техрайтер). Он готовит практически все виды таких материалов, включая руководства и справочники для пользователей, технические проекты для специалистов, маркетинговые тексты и т.д. К должностным обязанностям техрайтера относятся:

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

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

В идеале профессиональный технический писатель – это гуманитарий с техническим образованием

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

Подводим итоги

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

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

Apix-Drive — простой и эффективный коннектор систем, который поможет вам автоматизировать рутинные задачи и оптимизировать бизнес-процессы. Вы сможете экономить время и средства, направить эти ресурсы на более важные цели. Протестируйте ApiX-Drive и убедитесь, что этот инструмент разгрузит ваших сотрудников и уже после 5 минут настроек ваш бизнес начнет работать быстрее.

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

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

  • Требования — утверждения, которые идентифицируют атрибуты, возможности, характеристики или качества системы. Это основа того, что будет или было реализовано.
  • Архитектура / Дизайн — Обзор программного обеспечения. Включает отношения к среде и принципы построения, которые будут использоваться при проектировании компонентов программного обеспечения.
  • Технические — Документация кода, алгоритмов, интерфейсов и API.
  • Конечный пользователь — Руководства для конечный пользователь, системные администраторы и вспомогательный персонал.
  • Маркетинг — Как продвигать продукт и анализ рыночного спроса.
  • 1 Документация по требованиям
  • 2 Документация по проектированию архитектуры
  • 3 Техническая документация
    • 3.1 Техническая документация, встроенная в исходный код
      • 3.1.1 Грамотное программирование
      • 3.1.2 Разъяснительное программирование
      • 4.1 Составление пользовательской документации

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

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

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

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

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

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

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

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

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

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

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

      Когда речь идет о Relational Database Systems, документ должен включать следующие части:

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

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

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

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

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

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

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

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

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

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

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

        Пояснительное программирование

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

        См. также

        • API Writer
        • Сравнение генераторов документации
        • Дизайн по контракту
        • Проектный документ
        • Строка документации
        • Документация
        • Грамотное программирование
        • Файлы README
        • Помощь пользователям
        • Унифицированный язык моделирования UML

        Примечания

        Внешние ссылки

        • kelp — структура аннотации исходного кода для архитектурной, проектной и технической документации.
        • автоматизированная документация программного обеспечения — документация приложения

        Техническая документация в разработке ПО: кто, зачем, когда и как описывает проект

        image

        Привет! Меня зовут Даша Григорьева, я технический писатель в компании 65apps. Мы занимаемся разработкой сложных мобильных решений, и моя задача — подготовка технической документации по проектам. Очень часто роль технического писателя бывает недооцененной в компании (не у нас, конечно). Поэтому я хочу рассказать, зачем компании-разработчику нужен такой специалист, что такое технический проект, чем он отличается от ТЗ и почему это все необходимо для разработки мобильного приложения.

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

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

        Другой пример — государственные организации или организации, чья деятельность ограничивается или подчиняется законам и надзорным органам. Они обязаны осуществлять разработку ПО по всем правилам и с соблюдением всех стандартов. В таких проектах техническая документация, подготовленная по ГОСТам, — необходимое условие.
        И разумеется, грамотно составленная и актуальная документация необходима для того, чтобы каждый участник в процессе разработки мог обращаться к документам, если возникают вопросы по конкретной задаче или по всей системе в целом.

        Техническое задание и технический проект — два разных документа. Техническое задание отвечает на вопрос «что нужно сделать?», его составляет аналитик в самом начале проекта. Технический проект разрабатывает технический писатель. Этот документ создается после ТЗ и отвечает на вопрос «как нужно делать?».

        Кто пишет техническую документацию

        Обычно разработкой ТЗ занимается аналитик. Именно он общается с заказчиком / заинтересованным лицом и выявляет у него требования. В сложных случаях к процессу можно привлечь менеджера проекта, разработчиков, тестировщиков и других специалистов. Чем сложнее проект — тем больше требований к документации. Серьезные заказчики из крупных корпораций и госсектора требуют составлять документацию в соответствии с ГОСТами, а это задача очень трудоемкая, требующая внимательности к деталям и постоянной вовлеченности в процесс. И это не только ТЗ, но и технический проект, полностью описывающий все используемые в разработке решения, подходы и методологии. На него также распространяются ГОСТы. Подготовкой такой документации должен заниматься специалист — технический писатель.

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

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

        Кто такой технический писатель

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

        Для этого он собирает информацию и материалы от участников проекта и документирует эти данные согласно требованиям заказчика, в том числе и в соответствии с ГОСТами. Речь идет о ГОСТ 19 «Единая система программной документации» и ГОСТ 34 «Информационная технология. Комплекс стандартов на автоматизированные системы». Также технический писатель следит за актуальностью технической информации, если это необходимо на длительных и сложных проектах.

        Какая техническая документация нужна разработчику

        Рассмотрим идеальный с точки зрения ГОСТа процесс разработки системы.
        Все начинается с требований заказчика или заинтересованных лиц, которые необходимо выявить и обязательно зафиксировать в документе «Техническое задание».

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

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

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

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

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

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

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

        Когда составлять техническую документацию

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

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

        Если разработка идет по методологии Agile, то нет смысла прописывать всю документацию до старта работ. Если заказчику важно работать по спринтам и контролировать ход разработки, документацию можно дописывать параллельно основному процессу.
        В нашей компании возможны оба варианта — мы умеем адаптироваться под условия и пожелания заказчика.

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

        • технический писатель
        • техническое задание
        • техническая документация
        • Управление разработкой
        • Подготовка технической документации

        Документация на программу ГОСТ

        Техническая документация на программный продукт (программу) разрабатывается в соответствии с требованиями ГОСТ ЕСПД и её можно разделить на следующие категории:

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

        Различают следующую документацию на программный продукт

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

        Виды эксплуатационной документации и требования к ней

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

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

        Наши специалисты готовы разработать любой документы по требованиям ГОСТ ЕСПД.

        Оформите заявку и задавайте все интересующие вас вопросы по телефону +7(499)755-74-33 e-mail Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра. или через форму заказа.

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

        Все права защищены © 2023. SWRIT — разработка технической документации

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *