Документация

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Руководителю Аналитику Техническому писателю

Документация

Что такое документация?

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

Словом, это инструмент управления знаниями и фиксации информации.

---

Что такое документ?

Документ — это отдельный информационный артефакт, оформленный в соответствии с определённой структурой и стандартами, предназначенный для передачи, хранения или использования информации.

Документ может быть:

• электронным (PDF, Markdown, HTML);
• печатным (инструкция, отчёт);
• частью системы (man-страница, справка в приложении).

---

Какая бывает документация?

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

Это могут быть архитектурные решения (ADR), конспекты встреч, онбординг-гайды, внутренние API-спецификации и чек-листы деплоя. Разумеется, внутренняя документация, как правило, менее формальная, часто хранится в вики (Confluence, Notion) и доступна только по внутренним правам в закрытом пространстве.

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

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

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

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

Примеры технической документации - спецификации протоколов, руководства по развёртыванию кластеров, документации по API и описания форматов данных. Они отличаются высокой точностью, использованием терминов и схем, и имеют акцент на детали и параметры.

Пользовательская документация рассчитана на на конечных пользователей, которые могут не обладать техническими знаниями. Объясняет как использовать. Цель здесь научить выполнять задачи, минимизировать барьер входа, повысить удовлетворённость. Аудитория - обычные пользователи, офисные сотрудники, менеджеры, клиенты. Что очевидно, они могут быть менее технически «подкованными» и им важно подавать информацию под особым видом.

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

Временная документация - это документы, созданные на короткий срок для решения текущей задачи. Разумеется, это устаревает или удаляется. Цель здесь - зафиксировать промежуточные решения, организовать работу и передать информацию «здесь и сейчас». Примеры - протокол совещания, черновик спецификации, заметки на доске в Jira или какой-то временный гайд для тестирования. Порой даже просто сообщение-объявление. Всё это не требует идеального оформления, может храниться неструктурированно и со временем архивируется или удаляется.

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

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

---