Привет! Меня зовут Катя, я руководитель команды технических писателей в Ozon. Сейчас нас 11 человек на три платформы: пользовательскую доку, описание API и внутренние весьма технические штуки.
Как раз когда разбирала внутренние доки, разговаривала с лидами других команд и кандидатами на наши вакансии, поняла, что есть некоторая путаница в головах: не всегда понятно, какие документы нужны и кто должен их составлять.
Поэтому рассказываю, какие документы мы используем в Ozon и как мы их создаём.
Маленький хинт на старте:
в каждом документе за скобки вынесены технические писатели — они должны помогать делать текст полезным и понятным, следить за консистентностью терминов и оформления.
Аудитория: все сотрудники компании.
Цель: обеспечить совместимость процессов разных команд, уменьшить время на разработку велосипедов.
Участники: верхнеуровневые лиды, внутренний аудит.
В личном раю каждого перфекциониста все всё делают одинаково и правильно с первой попытки. Но в суровой реальности люди иногда проводят десятки встреч на выяснения, что правильнее использовать: camelCase или snake_case. Поэтому компании придумали (или поддержали) писать такие документы, в которых собраны общие рекомендации по ведению вообще всего.
Политики в общем описывают, что такое хорошо, а чего следует избегать. Как правило, они располагаются около онбордингов, чтобы новые сотрудники сразу пропитывались именно теми подходами, которые приняты в компании. Такие документы обязательно верифицируются топ-менеджментом: CTO, CPO, CEO и другими chief'ами.
Например, политика безопасности может рассказывать, почему в компании не принято использовать инструменты с открытым кодом, или почему нельзя использовать корпоративную сеть для скачивания торрентов.
Регламенты — дополнения к политикам с конкретными описаниями каких-то процессов, направленных на выполнение политик. Они пишутся руководителями направлений, часто всеми вместе, и живут рядом с политиками.
Это, например, описание выкатки фичи в прод, получения учётной записи для тестирования на контуре или любого другого процесса, единого внутри компании.
Важно не перестараться и не пытаться составить регламент настройки высоты стула, если это никак не влияет на цели и метрики продукта.
При написании регламентов и политик помните, что люди а) должны понимать, зачем они вообще написаны, и б) иметь возможность легко им следовать. Избегайте сложных конструкций вроде «Данная политика распространяется на лица, предполагающие наличие доступа к информационным системам...»
В моей первой команде техписателей мы иногда устраивали соревнование: надо было максимально усложнить предложение. Рекомендую, полезное упражнение на умение распознавать сложные конструкции. Но следите внимательно за местом практики, чтобы никто не подумал о реальном использовании соревновательных вариантов.
Аудитория: лиды, разработчики.
Цель: уменьшить количество встреч с объяснениями, как это всё устроено, ускорить онбординг, выявить и ликвидировать проектные костыли.
Участники: лиды, руководители направлений.
Эта та документация, где очень много схем с названиями модулей. Частая практика — перестать понимать как устроен проект, нанять техписателя или аналитика и посадить его описывать происходящее. Частая проблема при этом: не все держатели знаний готовы помогать документатору и отвечать на его вопросы.
Большинство проблем в процессах можно отловить, если внимательно слушать, о чём спрашивают сотрудники в первую неделю работы. И популярный вопрос для почесывания затылка — «А откуда мы берём эти данные?». В ответ на него хорошо бы подсунуть схему с большим заголовком «Как всё тут между собой работает», но обычно она существует только в коллективном разуме — и приходится писать в чаты, организовывать встречи или даже регулярные мероприятия на овермного специалистов.
Составление архитектурных документов любят поручать аналитикам, потому что надеются, что в процессе описания такой специалист выдаст море рекомендаций — и в компании наступит счастье. Но наступают почему-то только грабли.
Продолжу рекомендовать нанять опытного техписателя — он, возможно, и не выдаст полный анализ системы с планом развития на годы вперёд, но точно найдёт слабые места, пока будет проводить интервью с держателями знаний. Дальше уже можете отправить его на курсы аналитиков и развивать себе архитектора, а для поддержания документации взять стажера или младшего специалиста. Но очень прошу не смешивать роли: люди-оркесты в компаниях, бесспорно, могут быть полезными кадрами, но в целом на рынке это создаёт путаницу и огромную отдельную боль.
Аудитория: внешние пользователи.
Цель: уменьшить время на настройку системы, увеличить количество пользователей.
Участники: разработчики, тестировщики.
Внешними пользователями могут быть и внутренними разработчиками, если они ещё не изучили ваш модуль.
Под интеграционными документами понимаются вещи, которые объясняют как и зачем настраивать взаимодействие с продуктом.
Не самый обязательный документ, потому что часто информацию об интеграции можно достать из описания проекта, или же интеграция может быть дополненной архитектурой — дописываем требования к модулям и получаем интеграцию.
В обще виде для интеграционных документов характерны разделы:
Аудитория: новые сотрудники, сотрудники после ротации или упустившие какие-то нюансы.
Цель: снизить нагрузку с наставника и поднять у новеньких уровень понимания происходящего.
Участники: конкретная команда.
Здесь важнее, мне кажется, рассказать о самом процессе.
Соберите всю документацию, которая есть у команды. Про то, какая это должна быть документация и как её лучше собирать тема для отдельной статьи
Обратите внимание на тип документов: что они описывают, а какие темы не покрывают вообще. Специально не говорю какие это должны быть темы, чтобы у вас включался процесс мозгоштурма и анализ специфики конкретной команды.
После первого анализа отправляйтесь на встречу с лидом — пусть он расскажет о команде и процессах. Записывайте, задавайте вопросы и записывайте свои вопросы — именно они должны стать основой нового онбординга.
Найдите последнего пришедшего в команду человека, попросите написать те вопросы, которые он задавал в свои первые недели, и сверьте со своими. Вы восхитительны — теперь у вас есть рыба и можно начинать готовить онбординг.
Но ваша работа закончится только после первого обученного по вашему онбордингу сотрудника. Вам нужно будет переговорить с новеньким и сказать, мол, это свежая дока, мне очень важно твоё мнение — запиши, пожалуйста, все вопросы, которые у тебя возникнут в первые дни, укажи на места (в документе и в процессах), где ты что-то не понял.
Важно помнить, что и у вас, и у лидов уже есть опыт работы в компании и понимание общих терминов, процессов, жаргонизмов. И, скорее всего, вы их никак не отловите, потому что уже к ним привыкли. Поэтому ваш главный помощник при написании онбордингов — новый человек.
Из своего опыта — даю писать онбординги либо новым техписателям, либо тем, кто не пересекался ещё с командой-заказчиком. Так получается найти действительно самые основные вопросы.
Аудитория: все сотрудники.
Цель: давать точечные ответы, формировать основую базу знаний.
Участники: все сотрудники, часто и без техписателей.
Оно же «Архив», «Нечто», «Чёрная книжечка» и можете продолжить ряд в комментариях.
Велик соблазн просто закинуть эти статьи куда подальше и иногда кидать на них ссылку. Но, по мнению археологов, свалки — одни из ценнейших находок, потому что дают полную картину образа жизни исследуемого времени и народа. Противоречий не вижу, поэтому любую структуризацию, шаблоны и типовые документы рекомендую искать именно здесь.
Чтобы организовать документацию внутри компании, учитывайте:
habr.com
Как раз когда разбирала внутренние доки, разговаривала с лидами других команд и кандидатами на наши вакансии, поняла, что есть некоторая путаница в головах: не всегда понятно, какие документы нужны и кто должен их составлять.
Поэтому рассказываю, какие документы мы используем в Ozon и как мы их создаём.
Маленький хинт на старте:
при работе над любым документом важно в самом начале понять, кто и при каких условиях будет его читать. Если ответить на эти вопросы, станет понятно, что и как надо описывать. А иногда и не описывать вовсе, а показывать
в каждом документе за скобки вынесены технические писатели — они должны помогать делать текст полезным и понятным, следить за консистентностью терминов и оформления.
Регламенты и политики
Аудитория: все сотрудники компании.
Цель: обеспечить совместимость процессов разных команд, уменьшить время на разработку велосипедов.
Участники: верхнеуровневые лиды, внутренний аудит.
В личном раю каждого перфекциониста все всё делают одинаково и правильно с первой попытки. Но в суровой реальности люди иногда проводят десятки встреч на выяснения, что правильнее использовать: camelCase или snake_case. Поэтому компании придумали (или поддержали) писать такие документы, в которых собраны общие рекомендации по ведению вообще всего.
Политики в общем описывают, что такое хорошо, а чего следует избегать. Как правило, они располагаются около онбордингов, чтобы новые сотрудники сразу пропитывались именно теми подходами, которые приняты в компании. Такие документы обязательно верифицируются топ-менеджментом: CTO, CPO, CEO и другими chief'ами.
Например, политика безопасности может рассказывать, почему в компании не принято использовать инструменты с открытым кодом, или почему нельзя использовать корпоративную сеть для скачивания торрентов.
Регламенты — дополнения к политикам с конкретными описаниями каких-то процессов, направленных на выполнение политик. Они пишутся руководителями направлений, часто всеми вместе, и живут рядом с политиками.
Это, например, описание выкатки фичи в прод, получения учётной записи для тестирования на контуре или любого другого процесса, единого внутри компании.
Важно не перестараться и не пытаться составить регламент настройки высоты стула, если это никак не влияет на цели и метрики продукта.
При написании регламентов и политик помните, что люди а) должны понимать, зачем они вообще написаны, и б) иметь возможность легко им следовать. Избегайте сложных конструкций вроде «Данная политика распространяется на лица, предполагающие наличие доступа к информационным системам...»
В моей первой команде техписателей мы иногда устраивали соревнование: надо было максимально усложнить предложение. Рекомендую, полезное упражнение на умение распознавать сложные конструкции. Но следите внимательно за местом практики, чтобы никто не подумал о реальном использовании соревновательных вариантов.
Архитектуры
Аудитория: лиды, разработчики.
Цель: уменьшить количество встреч с объяснениями, как это всё устроено, ускорить онбординг, выявить и ликвидировать проектные костыли.
Участники: лиды, руководители направлений.
Эта та документация, где очень много схем с названиями модулей. Частая практика — перестать понимать как устроен проект, нанять техписателя или аналитика и посадить его описывать происходящее. Частая проблема при этом: не все держатели знаний готовы помогать документатору и отвечать на его вопросы.
Большинство проблем в процессах можно отловить, если внимательно слушать, о чём спрашивают сотрудники в первую неделю работы. И популярный вопрос для почесывания затылка — «А откуда мы берём эти данные?». В ответ на него хорошо бы подсунуть схему с большим заголовком «Как всё тут между собой работает», но обычно она существует только в коллективном разуме — и приходится писать в чаты, организовывать встречи или даже регулярные мероприятия на овермного специалистов.
Составление архитектурных документов любят поручать аналитикам, потому что надеются, что в процессе описания такой специалист выдаст море рекомендаций — и в компании наступит счастье. Но наступают почему-то только грабли.
Продолжу рекомендовать нанять опытного техписателя — он, возможно, и не выдаст полный анализ системы с планом развития на годы вперёд, но точно найдёт слабые места, пока будет проводить интервью с держателями знаний. Дальше уже можете отправить его на курсы аналитиков и развивать себе архитектора, а для поддержания документации взять стажера или младшего специалиста. Но очень прошу не смешивать роли: люди-оркесты в компаниях, бесспорно, могут быть полезными кадрами, но в целом на рынке это создаёт путаницу и огромную отдельную боль.
Интеграции
Аудитория: внешние пользователи.
Цель: уменьшить время на настройку системы, увеличить количество пользователей.
Участники: разработчики, тестировщики.
Внешними пользователями могут быть и внутренними разработчиками, если они ещё не изучили ваш модуль.
Под интеграционными документами понимаются вещи, которые объясняют как и зачем настраивать взаимодействие с продуктом.
Не самый обязательный документ, потому что часто информацию об интеграции можно достать из описания проекта, или же интеграция может быть дополненной архитектурой — дописываем требования к модулям и получаем интеграцию.
В обще виде для интеграционных документов характерны разделы:
- что это вообще такое и какие профиты от интеграции,
- какие требования есть у системы и какие нюансы стоит предусмотреть,
- сама инструкция вида «установите этот пакет, проверьте эти зависомости, наслаждайтесь нашим модулем»,
- типичные ошибки и раздел частых вопросов.
Онбординги
Аудитория: новые сотрудники, сотрудники после ротации или упустившие какие-то нюансы.
Цель: снизить нагрузку с наставника и поднять у новеньких уровень понимания происходящего.
Участники: конкретная команда.
Здесь важнее, мне кажется, рассказать о самом процессе.
Соберите всю документацию, которая есть у команды. Про то, какая это должна быть документация и как её лучше собирать тема для отдельной статьи
Обратите внимание на тип документов: что они описывают, а какие темы не покрывают вообще. Специально не говорю какие это должны быть темы, чтобы у вас включался процесс мозгоштурма и анализ специфики конкретной команды.После первого анализа отправляйтесь на встречу с лидом — пусть он расскажет о команде и процессах. Записывайте, задавайте вопросы и записывайте свои вопросы — именно они должны стать основой нового онбординга.
Найдите последнего пришедшего в команду человека, попросите написать те вопросы, которые он задавал в свои первые недели, и сверьте со своими. Вы восхитительны — теперь у вас есть рыба и можно начинать готовить онбординг.
Но ваша работа закончится только после первого обученного по вашему онбордингу сотрудника. Вам нужно будет переговорить с новеньким и сказать, мол, это свежая дока, мне очень важно твоё мнение — запиши, пожалуйста, все вопросы, которые у тебя возникнут в первые дни, укажи на места (в документе и в процессах), где ты что-то не понял.
Важно помнить, что и у вас, и у лидов уже есть опыт работы в компании и понимание общих терминов, процессов, жаргонизмов. И, скорее всего, вы их никак не отловите, потому что уже к ним привыкли. Поэтому ваш главный помощник при написании онбордингов — новый человек.
Из своего опыта — даю писать онбординги либо новым техписателям, либо тем, кто не пересекался ещё с командой-заказчиком. Так получается найти действительно самые основные вопросы.
Свалки полезностей
Аудитория: все сотрудники.
Цель: давать точечные ответы, формировать основую базу знаний.
Участники: все сотрудники, часто и без техписателей.
Оно же «Архив», «Нечто», «Чёрная книжечка» и можете продолжить ряд в комментариях.
Велик соблазн просто закинуть эти статьи куда подальше и иногда кидать на них ссылку. Но, по мнению археологов, свалки — одни из ценнейших находок, потому что дают полную картину образа жизни исследуемого времени и народа. Противоречий не вижу, поэтому любую структуризацию, шаблоны и типовые документы рекомендую искать именно здесь.
Важно только учитывать, что, если свалка появилась, значит, она решала какие-то проблемы — не забудьте эти проблемы найти и предусмотреть в новой структуре. Иначе новым, красивым и понятным, не будут пользоваться.
Резюме
Да, это не полный список. Я не рассказала про документации для API, SDK и про внешние пользовательские Помощи разных калибров. Но основные нужды внутри компании этот набор должен покрыть.Чтобы организовать документацию внутри компании, учитывайте:
- существующие документы — в них зарыты актуальные проблемы и процессы,
- вопросы новых сотрудников — они помогут сформировать полную картину необходимых знаний,
- межкомандные договорённости и процессы — они упрощают работу, но не всегда очевидны, поэтому их важно донести до всех заинтересованных,
- людей, процессы и отношения внутри компании — простое навязывание и запреты никогда не работает, поэтому
Какая документация нужна вашему проекту и кто должен её писать
Привет! Меня зовут Катя, я руководитель команды технических писателей в Ozon. Сейчас нас 11 человек на три платформы: пользовательскую доку, описание API и внутренние весьма технические штуки. Как раз...
habr.com