Недостаточно просто написать инструкции — важно, как, в каком порядке и где вы их разместите.
Привет! Это Теодора — технический писатель Платформы, жизненно важного департамента Ozon. Документация для нас имеет большое значение, потому что вся компания пользуется нашими разработками:
инфраструктурой as a service;
фреймворками и библиотеками на Go, C#, TypeScript;
трейсингом, мониторингом, логированием, нагрузочным тестированием;
инструментами для работы с базами данных и аналитикой;
виртуализацией и контейнеризацией.
Опираясь на свой опыт, я пошагово расскажу, как привести в порядок документацию технической команды, чтобы избавить коллег от однотипных вопросов и наладить межкомандную коммуникацию.
Дисклеймер: в этой статье упор сделан на содержание, структуру и формат. Сугубо гуманитарные вещи вроде орфографии и пунктуации обсуждать не будем — они на вашей совести.
Зачем вам документация
Документация — один из вариантов коммуникации. Обычно к ней прибегают, когда личное общение не решает проблему. Например, когда вы физически не успеваете до всех донести информацию, а кроме вас, это сделать никто не может.
Плюсы хорошей документации:
увеличивается bus-фактор: знание распространяется между большим числом людей, и его сложнее потерять;
команда не отвлекается на ответы на одни и те же вопросы и занимается своей работой;
коллеги быстро находят ответы (в том числе через
Ctrl+F), решают проблемы и разбираются в технологии: как следствие, увеличиваются их продуктивность и доход компании;для внешней документации: разгружает сотрудников техподдержки.
Да и, согласитесь, вам просто приятно читать документацию, в которой всё понятно описано и легко искать информацию. Если у вас есть примеры, делитесь в комментариях.
Хорошая ли у вас документация?
Пройдите маленький тест и посчитайте набранные баллы:
Результаты:
5 баллов: у вас хорошая документация, автор вами гордится!
0–4 балла: есть что доработать — переходите к практическим шагам.
У всех разные ситуации с документацией, поэтому алгоритм действий может различаться для каждого конкретного случая. В статье описаны десять шагов, но не все из них подойдут именно вам. Например, если у вас вообще нет документации, вам не нужно выполнять шаг про удаление неактуального.
Не торопитесь переходить к действиям — сначала налейте чай и просто прочитайте статью.
Шаг 1. Соберите всю информацию
Давайте посмотрим, какой материал у вас уже есть. Для этого соберите все описания вашей технологии из разных источников:
старая документация;
личные страницы — ваши и коллег (например, в Confluence);
ответы в чатах;
репозитории (например, в GitLab);
Word и другие текстовые редакторы;
ссылки в закладках браузера.
На будущее: никогда не дублируйте инструкции в разных ресурсах, так их будет сложнее поддерживать:
легче обновить одну, чем две;
одну из версий точно забудут обновить — и она будет вводить в заблуждение; как назло всегда будут находить именно её.
Шаг 2. Выбросите мусор
Одна актуальная статья лучше десяти устаревших.
Проверено: если у вас в документации найдут устаревшие сведения, никто не будет читать дальше — спросят у вас лично.
Самый важный шаг перед написанием документации — это избавление от устаревшей информации. Перечитайте всё, что собрали, и удалите неактуальные статьи, разделы и предложения.
Под «избавлением» имеется в виду одно из двух:
добавление в архив — предпочтительно;
безвозвратное удаление.
Если после этого вообще ничего не осталось, это нормально.
Если вы детально не знаете начинку описываемой технологии
Обычно это актуально для техписов, аналитиков и менеджеров, которые разработкой не занимались.
✅ Удачно: позвать на встречу или созвон эксперта из команды (обычно это тимлид или старший разработчик) и вычитать с ним весь материал полностью, не поверхностно.
❌ Неудачно: скинуть материал эксперту и попросить его самого удалить лишнее.
Если плохо выполнить этот шаг, вы потратите много времени зря в будущем. Проверено мной.
После такой «чистки» обычно очень легко дышится — будто камень с шеи снял.
Шаг 3. Найдите частые вопросы и сценарии
Наша новая задача — определить, что нужно задокументировать или актуализировать в первую очередь. Обычно это выясняется так:
Вы перечитываете все вопросы в чате за последний месяц, выписываете их на отдельную страницу (не удаляйте её) и считаете их количество.
Читаете комментарии с вопросами под инструкциями, если есть.
Опрашиваете аудиторию. Обычно это либо пост в публичном чате, либо вопросы знакомому коллеге лично. Формы с опросами, как правило, неэффективны, поскольку собирают мало ответов.
Продумываете популярные сценарии с командой, ведь лучше вас продукт никто не знает.
Вначале выпишите вопросы и сценарии, а потом начинайте писать для них тексты.
Если вашей разработкой пока никто не пользовался, будьте готовы собрать обратную связь после релиза и дописать то, что было неясно.
Шаг 4. Поделите на разделы
Цель — наметить примерный план будущей базы знаний. Он может дополняться, когда появятся новые данные, но пока нужно сделать «скелет» для всего остального.
Структура нужна, чтобы пользователю было понятно, в каком разделе искать нужную информацию. Это особенно актуально, если в вашей документации много страниц.
Добавить их все сплошным списком вразнобой — провальный вариант. Ctrl+F тут тоже не всегда поможет, потому что, например, вы пишете в названии страницы «кубер», а ваш читатель ищет «Kubernetes» или «k8s», ничего не находит — и идёт к вам в личку.
Целевая аудитория
Читатель должен видеть только то, что ему полезно. Разделяйте документацию в зависимости от потребностей аудитории.
Подумайте, какие люди будут её читать. Например:
только ваша команда;
другие команды, им нужна одна функциональность;
другие команды, им нужна разная функциональность;
и ваша команда, и другие команды.
Внешние команды не должны видеть странички «Черновик to do», «[убрать в архив] 2 декабря». Держите их в отдельной папке для черновиков.
Например, если ваша аудитория — продуктовые разработчики и команда мониторинга критичных сервисов, которые ищут в документации абсолютно разные вещи, разделите её соответствующим образом.
Шаг 5. Составьте словарь терминов
Одна сущность — один термин.
Договоритесь с командой, как вы что будете называть. Иногда один и тот же термин в разных компаниях используют по-разному, и это путает людей.
Термины должны легко находиться через Ctrl+F.
Неудачные варианты | Удачные варианты |
«Пушка», «долбилка» и «стрелялка»; | «Пушка» Почему: все коллеги в Ozon знают этот термин. |
«СronJob'ы», «кроны» и «джобы»; | «CronJob» Почему: все коллеги знают этот термин, он цельный. |
«Фэктори» и «фабрика», «эккаунт» и «аккаунт», «экшен» и «действие» | «Фабрика», «аккаунт» и «действие» Почему: популярные, понятные всем термины на русском языке. |
Если у вас в команде есть авторские разработки, названия которых придумали вы сами, заведите словарь терминов с пояснениями. Это особенно актуально, если статей много и неудобно в каждую добавлять расшифровки. Людям будет в разы проще вникнуть в вашу разработку: оставляете везде ссылку на словарь и радуетесь жизни.
Шаг 6. Утвердите правила для команды
Заранее обговорите с командой правила и план ведения документации.
Представим, что вы уже составили структуру базы по шагам выше и теперь её нужно поддерживать.
Обычно инструкции в команде пишут разные люди. Часто процессам ведения документации не уделяют должного внимания.
Если не договориться «на берегу», документация всегда превращается в хаос:
нет структуры — статьи добавляют куда попало;
никто не убирает устаревшую информацию;
команда не всегда знает, что у неё есть в документации;
много заброшенных статей;
много пустых статей из 2016 с пометкой «to do»;
перемешаны внутренние черновики и внешняя документация;
нет архива;
ведётся на русском, английском, латинском и древнегреческом.
Донесите до команды, что документация — это ваш общий продукт и от её качества зависит эффективность: ваша и других команд.
Пример правил по созданию новых страниц:
Черновик статьи создавайте в папке для черновиков.
Не добавляйте статью в список публичных, пока не допишете.
Чтобы перенести статью в список публичных:
отправьте её в чат команды;
её должны прочитать минимум два человека, дать обратную связь и утвердить;
решите с командой, в какой раздел её перенести.
Статью можно переносить.
Советую почитать о методике совместного ведения документации.
Шаг 7. Напишите тексты
Лучший способ научиться писать хорошие инструкции — это отдавать их на вычитку. Желательно — редактору. Если его нет — любому коллеге. Я не о проверке пунктуации, а о том, понятно ли написана статья, полная ли в ней информация.
Некоторые советы могут показаться сложными, но в них описаны базовые вещи.
Освойте инструменты форматирования там, где вы ведёте документацию. Примеры: макросы Confluence, синтаксис Markdown и HTML.
Укажите, для кого страница и что в ней описано, — тогда человек сразу поймёт, нужно ли ему это читать.
Не пишите сплошные тексты — делите их на логические абзацы и разделы. При грамотной вёрстке легче сходу найти ответ.
Добавляйте оглавление. Его цель — дать читателю возможность быстро понять, в какую часть текста ему нужно переместиться. Если оно получилось на сто пунктов, сократите его или разбейте статью на несколько.
Оформите разводящую страницу. Это главная страница с основной информацией и разделами по темам. Она нужна, чтобы читатель быстро понял, где искать необходимую инструкцию.
Пример Ozon Docs
Пример Yandex Cloud
Пример Amazon EC2Соблюдайте форматирование — не пишите весь текст в заголовке или жирным шрифтом, не создавайте таблицу в таблице, не убирайте весь текст под каты.
Добавляйте ссылки на другие инструкции и сервисы, если они упоминаются в тексте. Это сильно экономит время читателей. Может, они найдут устаревший дубль из шага 1.
Избегайте канцеляризмов — они утяжеляют тексты: «
для тогочтобы вданномпроцессеосуществить определённуюфункциональность».Выделяйте в тексте важное, но не превращайте его в одни сплошные плашки.
Укажите контакты команды, чтобы читатели знали, к кому обращаться.
Шаг 8. Добавьте FAQ
FAQ — страница с часто задаваемыми вопросами и ответами на них.
Многие технические писатели считают наличие FAQ признаком плохой структуры документации. Я же советую добавить эту страницу, потому что она может спасти ситуацию, если у вас не очень удачная разводящая страница.
Используйте список из шага 3, если он есть.
FAQ — это не полноценная инструкция. Не дублируйте тексты и не делайте ответы очень подробными.
Оптимальный вариант — краткий ответ со ссылкой на полную инструкцию. Например, «Да, это возможно. Подробнее в статье “Как создать N”».
Для продвинутых идеалистов:
Вопросы можно сгруппировать по темам — так их будет проще найти. Такие страницы FAQ обычно очень нравятся разработчикам, но это не принципиально, потому что обычно вопросы ищут с помощью Ctrl+F.
Шаг 9. Продумайте, как вашу документацию будут находить
Чтобы ваши труды не пропали даром, вашу документацию должно быть легко найти.
Подумайте, куда ваши коллеги чаще обращаются за помощью:
к вам в личку: закрепите ссылку на документацию у себя в профиле на корпоративном портале;
в ваш чат: закрепите ссылку в шапке, закреплённом сообщении, сделайте так, чтобы каждому вступившему ссылку отправлял бот;
в поиск Confluence: удалите устаревшую информацию, если ещё этого не сделали, чтобы она не всплывала, понятно называйте статьи.
Уведомите аудиторию, что у вас появилась документация, вы за ней следите и обращаться нужно именно туда.
Шаг 10. Проанализируйте результат
Лучший источник для анализа — ваша аудитория.
Есть несколько способов понять, решает ли проблемы ваша документация.
Что обычно делаю я:
Считаю количество запросов в чатах.
Провожу мини-исследование среди читателей: готовлю открытые вопросы, спрашиваю, долго ли они искали информацию, что именно они искали, нашли ли ответы на свои вопросы.
Изучаю статистику просмотров в Confluence и Grafana: если за месяц никто не обратился к документации, нужна ли она?
Сама не практикую, но отличная идея:
Добавить фичу «Оцените статью». Такие макросы точно есть в Confluence.
Если на этом этапе не всё гладко — это нормально, просто будьте готовы что-то дописать, поменять местонахождение статьи.
Итог
Наверное, достаточно информации за раз. Посоветуйтесь с командой, решите, нужна ли вам документация, есть ли ресурсы для её разработки и поддержки.
И помните, что документация — ваш общий продукт.
Буду рада ответить на ваши вопросы. Делитесь мнением и историями в комментариях.
