Привет! Меня зовут Катя, я руководитель команды технических писателей в Ozon. Сейчас нас 11 человек на три платформы: пользовательскую доку, описание API и внутренние весьма технические штуки.

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

Поэтому рассказываю, какие документы мы используем в Ozon и как мы их создаём.

Маленький хинт на старте:

при работе над любым документом важно в самом начале понять, кто и при каких условиях будет его читать. Если ответить на эти вопросы, станет понятно, что и как надо описывать. А иногда и не описывать вовсе, а показывать :)

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

Регламенты и политики

Аудитория: все сотрудники компании.

Цель: обеспечить совместимость процессов разных команд, уменьшить время на разработку велосипедов.

Участники: верхнеуровневые лиды, внутренний аудит.

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

Политики в общем описывают, что такое хорошо, а чего следует избегать. Как правило, они располагаются около онбордингов, чтобы новые сотрудники сразу пропитывались именно теми подходами, которые приняты в компании. Такие документы обязательно верифицируются топ-менеджментом: CTO, CPO, CEO и другими chief'ами.

Например, политика безопасности может рассказывать, почему в компании не принято использовать инструменты с открытым кодом, или почему нельзя использовать корпоративную сеть для скачивания торрентов.

Регламенты — дополнения к политикам с конкретными описаниями каких-то процессов, направленных на выполнение политик. Они пишутся руководителями направлений, часто всеми вместе, и живут рядом с политиками.

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

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

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

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

Архитектуры

Аудитория: лиды, разработчики.

Цель: уменьшить количество встреч с объяснениями, как это всё устроено, ускорить онбординг, выявить и ликвидировать проектные костыли.

Участники: лиды, руководители направлений.

Это та документация, где очень много схем с названиями модулей. Частая практика — перестать понимать как устроен проект, нанять техписателя или аналитика и посадить его описывать происходящее. Частая проблема при этом: не все держатели знаний готовы помогать документатору и отвечать на его вопросы.

Большинство проблем в процессах можно отловить, если внимательно слушать, о чём спрашивают сотрудники в первую неделю работы. И популярный вопрос для почесывания затылка — «А откуда мы берём эти данные?». В ответ на него хорошо бы подсунуть схему с большим заголовком «Как всё тут между собой работает», но обычно она существует только в коллективном разуме — и приходится писать в чаты, организовывать встречи или даже регулярные мероприятия на овермного специалистов.

Составление архитектурных документов любят поручать аналитикам, потому что надеются, что в процессе описания такой специалист выдаст море рекомендаций — и в компании наступит счастье. Но наступаются почему-то только грабли.

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

Интеграции

Аудитория: внешние пользователи.

Цель: уменьшить время на настройку системы, увеличить количество пользователей.

Участники: разработчики, тестировщики.

Внешними пользователями могут быть и внутренние разработчики, если они ещё не изучили ваш модуль.

Под интеграционными документами понимаются вещи, которые объясняют как и зачем настраивать взаимодействие с продуктом.

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

В обще виде для интеграционных документов характерны разделы:

• что это вообще такое и какие профиты от интеграции,

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

• сама инструкция вида «установите этот пакет, проверьте эти зависомости, наслаждайтесь нашим модулем»,

• типичные ошибки и раздел частых вопросов.

Не очень люблю частые вопросы, потому что это свалка вещей, которые не влезли в основные разделы и приучают пользователя не читать всё, а пробежаться только по ним. Это неплохо с точки зрения решения проблем документацией, но это воспитывает очередное «зачем читать доку, если можно потыкаться и потом почитать ошибки».

Онбординги

Аудитория: новые сотрудники, сотрудники после ротации или упустившие какие-то нюансы.

Цель: снизить нагрузку с наставника и поднять у новеньких уровень понимания происходящего.

Участники: конкретная команда.

Здесь важнее, мне кажется, рассказать о самом процессе.

Соберите всю документацию, которая есть у команды. Про то, какая это должна быть документация и как её лучше собирать тема для отдельной статьи :) Обратите внимание на тип документов: что они описывают, а какие темы не покрывают вообще. Специально не говорю какие это должны быть темы, чтобы у вас включался процесс мозгоштурма и анализ специфики конкретной команды.

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

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

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

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

Из своего опыта — даю писать онбординги либо новым техписателям, либо тем, кто не пересекался ещё с командой-заказчиком. Так получается найти действительно самые основные вопросы.

Свалки полезностей

Аудитория: все сотрудники.

Цель: давать точечные ответы, формировать основную базу знаний.

Участники: все сотрудники, часто и без техписателей.

Оно же «Архив», «Нечто», «Чёрная книжечка» и можете продолжить ряд в комментариях.

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

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

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

Резюме

Да, это не полный список. Я не рассказала про документации для API, SDK и про внешние пользовательские Помощи разных калибров. Но основные нужды внутри компании этот набор должен покрыть.

Чтобы организовать документацию внутри компании, учитывайте:

• существующие документы — в них зарыты актуальные проблемы и процессы,

• вопросы новых сотрудников — они помогут сформировать полную картину необходимых знаний,

• межкомандные договорённости и процессы — они упрощают работу, но не всегда очевидны, поэтому их важно донести до всех заинтересованных,

• людей, процессы и отношения внутри компании — простое навязывание и запреты никогда не работает, поэтому

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

А чтобы повышать насмотренность и иметь возможность выбрать из множества подходов — подписывайтесь на Блог компании Ozon Tech :) Мы уже готовим новые статьи про документацию и не только!