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