Документация
Документация
Что такое документация?
Документация — это совокупность документов, созданных для описания, объяснения, сопровождения или управления продуктом, системой, процессом или проектом. Её целью является обеспечение понимания, упрощение использования и развития, снижение зависимости от отдельных специалистов и обеспечение преемственности и контроля.
Словом, это инструмент управления знаниями и фиксации информации.
Что такое документ?
Документ — это отдельный информационный артефакт, оформленный в соответствии с определённой структурой и стандартами, предназначенный для передачи, хранения или использования информации.
Документ может быть:
- электронным (PDF, Markdown, HTML);
- печатным (инструкция, отчёт);
- частью системы (man-страница, справка в приложении).
Какая бывает документация?
Внутренняя документация - это документация, предназначенная для использования внутри организации или команды, не рассчитанная на публикацию или доступ со стороны. Она позволяет поддерживать разработку, передавать знания и стандартизировать процессы для разработчиков, тестировщиков, DevOps, менеджеров и технических писателей конечно.
Это могут быть архитектурные решения (ADR), конспекты встреч, онбординг-гайды, внутренние API-спецификации и чек-листы деплоя. Разумеется, внутренняя документация, как правило, менее формальная, часто хранится в вики (Confluence, Notion) и доступна только по внутренним правам в закрытом пространстве.
Внешняя документация - это документация, предназначенная для внешних пользователей, таких как клиенты, партнёры, интеграторы, разработчики. Она помогает использовать продукт, снижает нагруку на поддержку и повышает вовлечённость.
К примеру, это руководство пользователя, API-документация на публичном портале, FAQ на сайте, инструкция по настройке интеграции. Часто это требует высокой точности и ясности, проходит редактуру и локализацию, и такая документация должна соответствовать бренду и стандартам UX.
Иногда документация может иметь внутренний вариант (для своих) и внешний (для всех). Допустим, когда закрытая информация «прячется» от чужих глаз.
Техническая документация ориентирована на специалистов, обладающих техническими знаниями. Объясняет как устроено и как работает. Цель её - описать архитектуру, объяснить принципы работы, помочь в интеграции или настройке инженерам, разработчикам, DevOps, системным администраторам.
Примеры технической документации - спецификации протоколов, руководства по развёртыванию кластеров, документации по API и описания форматов данных. Они отличаются высокой точностью, использованием терминов и схем, и имеют акцент на детали и параметры.
Пользовательская документация рассчитана на на конечных пользователей, которые могут не обладать техническими знаниями. Объясняет как использовать. Цель здесь научить выполнять задачи, минимизировать барьер входа, повысить удовлетворённость. Аудитория - обычные пользователи, офисные сотрудники, менеджеры, клиенты. Что очевидно, они могут быть менее технически «подкованными» и им важно подавать информацию под особым видом.
К примеру, это пошаговое руководство, видеоинструкция по настройке приложения, карточки подсказок. Язык здесь проще, каждый шаг подробно описывается, добавляются скриншоты, иллюстрации, а фокус больше на решении задачи, а не на технике. Пользователю плевать, как это работает, ему важно - как это сделать.
Временная документация - это документы, созданные на короткий срок для решения текущей задачи. Разумеется, это устаревает или удаляется. Цель здесь - зафиксировать промежуточные решения, организовать работу и передать информацию «здесь и сейчас». Примеры - протокол совещания, черновик спецификации, заметки на доске в Jira или какой-то временный гайд для тестирования. Порой даже просто сообщение-объявление. Всё это не требует идеального оформления, может храниться неструктурированно и со временем архивируется или удаляется.
Долгосрочная документация включает в себя документы, предназначенные для длительного хранения и регулярного использования. Это обеспечивает преемственность, возможность поддерживать продукт годами и позволяет служить официальным источником истины.
Примерами могут быть руководство пользователя, политика безопасности, архитектурная документация. В отличие от прочих, эта документация проходит ревью и утверждение, версионируется, поддерживается актуальной, часто интегрирована в систему управления документацией.