Техническая документация – что это такое, какой она должна быть и кто ее создает?
Подготовка документации на программное обеспечение является очень важным этапом процесса его разработки и выпуска. К сожалению, далеко не все компании уделяют ей достаточно внимания, что негативно сказывается как на обслуживании и развитии ПО, так и на взаимодействии с его пользователями.
Содержание:
1. Что такое техническая документация на ПО? Ее виды и форматы
2. Какой должна быть качественная документация?
3. Что такое техническое задание и технический проект?
4. Кто такой технический писатель? Особенности, задачи и проблемы этой профессии
5. Подводим итоги
В нашей новой статье мы расскажем о том, какую пользу и преимущества предоставляет грамотная техдокументация. Вы узнаете, какая документация считается качественной и что она должна включать, какие виды и форматы таких материалов существуют и чем они отличаются друг от друга. Кроме того, мы расскажем про профессию технического писателя (техрайтера), что он должен уметь и какая сейчас ситуация на рынке этих специалистов.
Что такое техническая документация на ПО? Ее виды и форматы
Документация на программное обеспечение (software documentation) – это комплекс документов, в которых подробно описываются технические характеристики и потребительские качества ПО, а также сведения о процессе его разработки, применения и сопровождения.
Пакет документации на ПО включает не только технические материалы, но и множество других видов документов. К ним относятся руководства, инструкции и справки для пользователей, обзоры программного обеспечения, спецификации, методики тестирования и т.д. Для удобства классификации вся эта документация делится на 4 категории:
- Проектная (архитектурная). Описывает основные положения, цели, задачи и этапы проекта, которые применяются при создании программного обеспечения и его рабочей среды. Представляет собой общий обзор ПО, предназначенный, прежде всего, для работающих над проектом специалистов.
- Техническая. Иногда так называют абсолютно всю документацию для программного обеспечения, хотя это не совсем верно. Непосредственно техдокументация включает описание программного кода и выполняемых им функций, структур данных, алгоритмов, API и интерфейсов. Кроме того, в ней подробно отображается процесс разработки ПО, принцип его действия и порядок эксплуатации. Часто такие материалы поставляются в комплекте с исходным кодом программы или же встраиваются в него в виде комментариев. Для упрощения создания и обновления техдокументов используют специальные шаблоны или делают это автоматизировано при помощи генераторов документации (Javadoc, Doxygen, NDoc и т.д.).
- Пользовательская. Если первые два вида материалов ориентированы на специалистов, то эта категория предназначена для пользователей программного обеспечения. В ней нет сложных технических описаний кода и принципов его работы, вместо этого она сосредоточена на описании функций ПО и правил его эксплуатации. Среди наиболее распространенных форматов пользовательской документации можно отметить краткое руководство пользователя (User's Guide) и подробный справочник пользователя (User's Reference). Также она нередко содержит инструкцию по решению проблем и ответы на часто задаваемые вопросы.
- Маркетинговая. Еще одним из основных видов документации на ПО являются маркетинговые материалы, которые помогают привлечь внимание целевой аудитории к продукту, рассказать о его предназначении, возможностях и преимуществах. В отличие от пользовательской, маркетинговая документация гораздо более краткая. Часто она состоит из одного рекламного буклета, предназначенного для ознакомления пользователя с программой или приложением.
Какой должна быть качественная документация?
Прежде всего, она должна соответствовать определенному набору стандартов. А именно, таким, как:
- Структурированность. Наличие четкой структуры является одним из важнейших требований к технической документации. Она должна быть логически упорядочена в разделы и подразделы, иметь абзацы, списки и другие элементы форматирования текста. Если речь идет о пользовательских мануалах, то одним лишь текстовым описанием здесь не обойтись – его нужно дополнять скриншотами программы в высоком качестве. Не менее популярными считаются видео-мануалы, которые, впрочем, не могут полностью заменить собой текстовые материалы.
- Единообразие. Вся документация на программное обеспечение должна быть оформлена в едином формате, включая как проектные и технические документы для сотрудников, так и материалы для пользователей. Кроме того, в ходе ее составления следует сверяться с другими документами, выпущенными вашей компанией, чтобы придерживаться единого корпоративного стиля. Нелишним также будет заранее стандартизировать процесс подготовки документации, чтобы избежать каких-либо расхождений в дальнейшем.
- Информативность. Еще одним важным признаком качественной документации на ПО является ее понятность и информативность. Для достижения этой цели нужно уметь соблюсти баланс между объемом данных и простотой их изложения. Ухудшить этот показатель может как недостаток, так и избыток информации, особенно, когда дело касается документации для пользователей. С одной стороны, не нужно делать ее излишне поверхностной и упрощенной, а с другой нельзя допустить чрезмерного усложнения материала.
- Релевантность. Хорошая техническая документация обязательно должна быть предназначена для определенной целевой аудитории. Создание общего универсального руководства для разработчиков и пользователей – это интересная, но трудновыполнимая задача, которая вряд ли будет под силу даже опытному техрайтеру. Перед разработкой материалов желательно определить круг сотрудников или клиентов, для которых они будут максимально полезны и интересны. Также необходимо иметь представление об уровне подготовки аудитории и о том, какие ее задачи и проблемы сможет решить эта документация.
Что такое техническое задание и технический проект?
Как правило, всю техническую документацию необязательно прописывать до начала разработки программного обеспечения. Чаще всего современные IT-проекты создаются по методологии Agile, а работа над ними ведется по спринтам, что позволяет писать документацию параллельно с процессом разработки.
- Автоматизируйте работу интернет магазина или лендинга
- Расширяйте возможности за счет интеграций
- Не тратьте деньги на программистов и интеграторов
- Экономьте время за счет автоматизации рутинных задач
Однако есть несколько документов, которые в идеале должны быть подготовлены до старта разработки ПО: к ним относится техническое задание (ТЗ) и технический проект (ТП).
Техническое задание является ключевым предварительным документом, в нем представлено общее описание и назначение программы, ее бизнес-цели, предполагаемый объем работ, а также порядок этапов разработки, оценки и приемки ПО. ТЗ составляется бизнес-аналитиком после переговоров с заказчиком, поэтому в нем нужно точно и подробно зафиксировать все его требования и видение будущей программы. При необходимости, также его обсуждают с участниками команды-исполнителя проекта: разработчиками, дизайнерами, проект-менеджерами и т.д. Фактически, это выраженная в документальной форме постановка задачи.
После составления и согласования технического задания начинается работа над техническим проектом, который уже готовит техрайтер, а не бизнес-аналитик. ТП представляет собой комплект материалов, в котором описывается архитектура, сценарии, методы, подходы, технические решения и другие данные, применяемые при разработке программы. Например, в техническом проекте отображают структуру серверов и баз данных, макеты интерфейсов, описания алгоритмов и интеграций с внешними системами или оборудованием, пользовательские сценарии и т.д.
Говоря простым языком, если техническое задание отвечает на вопрос «что нужно сделать?», то технический проект – на вопрос «как это сделать?».
Кто такой технический писатель? Особенности, задачи и проблемы этой профессии
Разработкой технической документации на программное обеспечение занимается технический писатель (technical writer, техрайтер). Он готовит практически все виды таких материалов, включая руководства и справочники для пользователей, технические проекты для специалистов, маркетинговые тексты и т.д. К должностным обязанностям техрайтера относятся:
- Оформление технической документации в соответствии с внутренними (корпоративными), государственными или международными стандартами.
- Внесение в документацию изменений и дополнений по мере обновления ПО, поддержание ее в актуальном состоянии.
- Подготовка графических и медиа-материалов (схем, графиков, скриншотов, видео-гайдов) по заданным параметрам и внесение их в техническую документацию.
- Тестирование и анализ новых программ и приложений, применение полученного опыта и знаний при составлении документации.
- Сбор необходимых сведений о ПО у всех участников проекта: разработчиков, менеджеров, дизайнеров, тестировщиков, заказчиков и т.д.
- Перевод технической документации на иностранные языки, подготовка технических презентаций, участие в процессах внедрения программного обеспечения.
В идеале профессиональный технический писатель – это гуманитарий с техническим образованием, который понимает основы IT-разработки, владеет специализированной терминологией, знает некоторые языки программирования и языки разметки, а также средства автоматизации процессов документирования. При этом он должен иметь определенные филологические навыки, чтобы составлять технический материал кратко, информативно и понятно как для специалистов, так и для обычных пользователей.
Однако подобная универсальность и многозадачность доступна немногим, поэтому IT-компании часто жалуются на сложность поиска хорошего техрайтера. С одной стороны, лучше всех о ПО расскажут его разработчики, однако они не умеют представить программу лаконично и понятно для неспециалиста. А профессиональные авторы текстов, как правило, не разбираются в программировании, поэтому не могут точно и информативно описать структуру, функции и другие технические нюансы ПО.
Подводим итоги
Документация на программное обеспечение включает 4 основных вида материалов: проектные, технические, пользовательские и маркетинговые. Ее можно составлять параллельно с разработкой ПО, заранее нужно подготовить только техническое задание и технический проект. Качественная документация обязательно должна иметь четкую структуру, быть оформлена в едином формате, быть понятной и информативной как для специалистов, так и для пользователей.
Помимо этого, важнейшим свойством технической документации является ее соответствие запросам и потребностям целевой аудитории. Написанием технической документации занимается отдельный специалист – техрайтер. Он должен не только писать и редактировать соответствующие тексты, но также готовить графику, видео и презентации, собирать сведения о ПО, переводить документацию на иностранные языки, тестировать и анализировать программы и приложения.
Apix-Drive — простой и эффективный коннектор систем, который поможет вам автоматизировать рутинные задачи и оптимизировать бизнес-процессы. Вы сможете экономить время и средства, направить эти ресурсы на более важные цели. Протестируйте ApiX-Drive и убедитесь, что этот инструмент разгрузит ваших сотрудников и уже после 5 минут настроек ваш бизнес начнет работать быстрее.