Документация: почему так важно её вести и как это делать

Зачем нужна документацияЗачем нужна документация

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

Такая ситуация называется bus factor (фактор автобуса): проект останавливается, если один из участников «попадает под автобус», потому что остальные не могут разобраться в процессах без него.

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

Кто этим занимаетсяКто этим занимается

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

В обязанности технического писателя входит:

• собирать и систематизировать данные о продукте;

• проводить интервью с разработчиками для получения информации;

• редактировать и обновлять документацию, например когда выходит новая версия программы;

• создавать и вести внутреннюю базу знаний для сотрудников.

Однако такой специалист есть не во всех компаниях, поэтому многие сотрудники ведут документацию самостоятельно.

Как начать документироватьКак начать документировать

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

• Процесс повторяется регулярно, а не один раз. Например, разовый процесс — команда три года работала в инструменте Jira, а теперь переходит в ClickUp. Документировать этот переход не обязательно. Повторяющийся процесс — участники команды регулярно ставили друг другу задачи в Jira, а теперь будут ставить в ClickUp. Как это делать в новом инструменте, нужно задокументировать.

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

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

• Confluence — разработан специально для документирования и создания баз знаний на проектах. Есть готовые шаблоны, в том числе для документации. В сервисе можно создавать иерархическое дерево страниц, помечать их метками, добавлять перекрёстные ссылки. Есть возможность командной работы и встроенные интеграции с другими продуктами Atlassian: Jira, Trello.

• Notion — сервис для создания текстовых документов, списков дел, баз данных, таблиц, баз знаний, ведения проектов и командной работы. Есть готовые шаблоны под задачи разных отделов: маркетинг, дизайн, разработка, HR, продажи. Поддерживает подсветку синтаксиса для более чем 60 языков программирования. Есть встроенные интеграции со всеми популярными сервисами: Figma, Jira, Github, Slack, Asana и другими.

• Archbee — сервис для создания технической документации. Поддерживает списки, таблицы, загрузку файлов, изображений и видео, многоязычное редактирование кода и создание диаграмм. Интегрируется с разными инструментами разработчика: Mermaid для построения диаграмм на JavaScript, Swagger для создания клиентских библиотек, языком запросов GraphQL и другими.

• Docsie — сервис для создания документации по продукту. Можно использовать для создания как внутренних, так и внешних инструкций. Позволяет собирать текстовые отзывы от пользователей, чтобы улучшать документы. Есть встроенный переводчик на базе нейросети, но русский язык не поддерживается.

• Miro — сервис для планирования и визуализации идей. Его можно использовать как основную платформу для ведения документации в виде блок-схем, канбан-досок и инфографики, а также как дополнительный инструмент: у Miro есть встроенные интеграции с Confluence и Notion.

Придумайте структуру документа. Чтобы сэкономить время, создайте единый шаблон для документации. Добавьте в шаблон разделы, которые помогут пользователям легко выполнить описанное:

• Краткие сведения, для чего существует процесс.

• Кто основные участники процесса (разработчики, маркетологи, дизайнеры).

• Что нужно для выполнения процесса (ПО, ресурсы).

3 правила, как вести документацию3 правила, как вести документацию

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

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

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