Перейти к основному содержимому

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

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ
Руководителю Аналитику Техническому писателю
Теория данных (раздел 3)

ERD и словарь сущностей — Entity Relationship, нормализация, SQL. Карта — о разделе.

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

Документ — один артефакт (файл, страница, PDF). Документация — совокупность таких артефактов вокруг продукта или процесса. Дальше — как их делят по аудитории и сроку жизни; виды по ролям (API, ТЗ, runbook) — в следующей главе.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Как расширять документацию, чтобы она реально помогала​

Если коротко: полезная документация отвечает не на вопрос "что мы написали", а на вопрос "что читатель сможет сделать после прочтения".

Практический подход:

  1. Добавляйте в начало документа блок "Для кого и зачем" (роль читателя + ожидаемый результат).
  2. После каждого перечисления давайте расшифровку "когда это нужно" и "что будет, если этого нет".
  3. Для каждой процедуры приводите минимальный пример — входные данные, шаги, результат, типичная ошибка.
  4. В конце документа держите блок "См. также" с ссылками на соседние статьи.
  5. Назначайте владельца документа и дату пересмотра, чтобы материал не устаревал незаметно.

Мини-шаблон, который можно применить почти к любой статье:

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

Продолжение темы:

В подборках​

Статья входит в тематические подборки и блок "С чего начать?" на главной. Соседние шаги того же маршрута:

Офисная грамотность — Офисные пакеты, Текст — о разделе, Электронная почта, Цифровые формы и анкеты, Устройство и надёжность паролей, Архитектура десктопных приложений.

Содержание