Ситуация: открываете базу знаний и понимаете — что-то с ней не так. Поиск неудобный, статьи устарели, материалы повторяются, а некоторые ключевые вещи вообще отсутствуют. И каждый раз кто-то приходит с одними и теми же вопросами. Вы — тимлид/техлид/knowledge-менеджер, который знает ответы на все вопросы. Но времени на работу не остаётся как раз из-за разрешения всяких мелочей. Знакомо?
Привет, Хабр! Меня зовут Анастасия Граф. Я руковожу отделом разработки технической документации в Maxim Technology — компания делает Ride Tech сервис для такси Maxim. Мы первыми в России запустили цифровую платформу. Этот материал готовился по мотивам доклада для TeamLead Conf.
В предыдущей части статьи об организации Базы знаний мы сформулировали универсальные требования к ней и разобрались, с чего начать в принципе на примере процессов в Maxim Technology. Сегодня выясним, зачем нужно ревью любой документации и как оно поможет повысить уровень знаний в командах.
Типы контента и кто им занимается
Документацию кто-то должен создавать. Эту задачу можно возложить на разных специалистов:
технический писатель/аналитик
Это самое очевидное решение, но ни того, ни другого в команде может не быть.
тестировщик / специалист сопровождения
Это распространённый кейс и он ничему не противоречит. Иногда документацию пишет саппорт, обычно третья линия (L3), реже — вторая (L2). А вот первая линия ничего не пишет.
разработчик
У нас были случаи, когда разработчики писали сами. Но надо быть готовым к тому, что им потребуется помощь — проверить стиль, вёрстку и т.д.
кто-то ещё
Менеджер, секретарь проекта или любой другой человек, способный справиться с задачей.
Создавать документацию — непростая задача. Авторы могут прекрасно справиться со статьёй для одних целей и не могут написать её для других даже в рамках одной темы.
Для себя я делю контент на четыре типа и для каждого из них выделяю оптимального автора и алгоритм верификации написанного:
бизнес-описания — нужны для понимания реализации функционала;
технические описания — содержат глубокую информацию для разработчиков или L3, которая может что-то поправить;
пользовательская документация — руководство пользователя, включая раздел часто задаваемых вопросов;
документация сопровождения — обеспечивает работу поддержки.
Возможно, у вас будут другие, это не повлияет на подход. От типа контента зависят требования к содержанию и виды шаблонов, упрощающих вход в обмен знаниями. Есть мелкие нюансы.
Теперь рассмотрим каждый из типов контента базы знаний предметнее.
Бизнес-описания
Это описание системы или продукта с точки зрения выполнения требований коммерции: как бизнес захотел, так мы и написали в соответствии с постановкой задачи при реализации фичи.
Бизнес-описание в нашем случае, как правило, готовит технический писатель.
Например, я пришла в компанию с амбициозной задачей — описать всё сделанное за много лет в книгу, которая станет руководством менеджера. Он сможет что-то донастроить и понять принцип работы. Мы планировали решить задачу за год, но получилось за полтора.
У меня была джунская команда: начинали четверо, а в конце было десят�� человек. Бизнес-описание готовили исключительно технические писатели. Они консультировались по непонятным вопросам с разработчиками — бизнес-аналитиков у нас нет.
Ориентироваться на джунов — это хороший подход. Когда функцию технического писателя выполняет кто-то другой, он делает это на уровне джуна-техписа. Нам нужно было выстроить процессы так, чтобы качество документации было приемлемым. Первое, что мы ввели — внутреннее ревью.
Внутреннее ревью
Под ним мы понимали передачу готового текста на вычитку своему коллеге внутри команды. Это необходимо для оценки написанного.
Люди с разной скоростью усваивают информацию и по-разному погружаются. Тем, кто справлялся быстрее, отдавали документацию на внутреннее ревью. Потом мы поняли, что было бы неплохо верифицировать содержание.
Ревью заказчика/потенциального читателя
Добиться ревью непросто. Поэтому вначале мы просили дать ревью кого-то одного. В какой-то момент начали приходить люди, которые уже сами хотели помочь с описаниями, чтобы ускорить процесс.
Мысль о том, что иногда процесс зависает, не должна вас останавливать — вам просто нужно продать ценность. Мы пошли к замтехдиректора: он прочитал, показал, что не так, мы скорректировали. А потом обратились к другим сотрудникам через все возможные каналы с просьбой предоставить фидбэк. У нас на каждой странице есть призыв с просьбой дать обратную связь. Это помогло понять, что потенциальный читатель хочет видеть на странице.
Прозрачный алгоритм корректировок по обратной связи
Обратная связь пре��ратится в момент, когда люди перестанут верить, что вы читаете их отзывы. Поэтому когда нам приходит сообщение от конкретного человека, на следующей неделе в нашем канале появляется запись в духе: «По обратной связи от N мы изменили в этой статье вот это». А ещё тэгнем его и лично напишем сообщение с благодарностью.
Внутреннее ревью
Разберём, что делает человек, который проводит ревью внутри команды.
Проверка логики изложения.
Во время написания текста автор так глубоко погружается в проблему, что наступает «проклятие знаниями». Ему видится всё простым, а стороннему читателю уже непонятно. Кроме того, порой из-за усталости от темы начинает сбиваться логика повествования. Это лечится внутренним ревью.
Проверка ошибок.
Орфография, пунктуация, абзац на семь-восемь строк из одного предложения или наоборот, короткие, рубленые фразы — со всем этим поможет человек, у которого ещё не замылен взгляд на текст.
Уточняющие вопросы.
По ходу чтения ревьюер задаёт уточняющие вопросы обо всём, что ему показалось непонятным или в чём он не уверен. Сюда же относятся и дополнения.
Воспроизведение алгоритмов, описанных в инструкциях.
Это очень важный этап. Ревьюер должен воспроизвести описанное руководство и убедиться, что с его помощью можно достичь заявленных целей. Часто случается так, что алгоритмы не работают — например, кому-то не хватило прав, а у кого-то старый кэш.
Зачем делать это внутри команды:
во-первых, так мы улучшаем текст;
во-вторых — п��является ещё один человек, который погрузился в тему, не готовя документацию. Если первый уйдёт в отпуск, материал подхватит второй.
Я бы хотела оказаться внутри такой экосистемы, когда есть отдельные роли (и это три разных человека):
кто пишет первичный текст;
кто редактирует этот текст;
кто после правок его ещё раз редактирует.
В нашем случае схема другая:
кто-то проводит внутреннее ревью — пишет замечания и предложения;
автор изначального текста корректирует по итогам ревью;
возврат к п.1 и так до состояния, пока больше замечаний не будет.
Обратная связь от пользователей
На каждой странице разрабатываемого документа мы обращаемся к пользователям с просьбой дать обратную связь, пишем в мессенджерах и т.д.
Относительно недавно у нас появились менеджеры, которые занимаются предложениями по изменению функционала. В идеале они опираются на документацию, но на практике — не всегда. Если мы замечаем, что информация из доклада не была учтена, мы напоминаем, что документ — первичен, а чат с коллегами — вторичен.
Но важно понимать: это не быстрый процесс. Такие изменения происходят на уровне культуры.
Технические описания
Это описание системы или продукта с точки зрения технических решений, особенностей, нюансов реализации и всего, что нужно для разработки.
Техническое описание обычно готовит технический писатель по постановке аналитики или разработчик, если её нет.
У нас очень много функционала было реализовано до появления команд аналитиков и технических писателей четыре года назад. Поэтому здесь нам помогают ребята из разработки. Самое сложное — выбрать подходящий всем и результативный формат работы.
В одной из итераций мы ходили к одному супер-заинтересованному лиду, который хотел подготовить техническую документацию на кусок функционала. Он предложил формат, где он рассказывает, мои писатели делают из этого черновики и он правит уже почти готовое. Полгода длилась такая история: трижды раза в неделю созванивались на два часа, технический писатель собирал материалы и отдавал лиду на ревью. В конце лид пришёл ко мне и сказал: «Безнадёжны твои техписы, всё плохо, так не работает». Мы перестали так делать и предложили ребятам написать самим или наговорить на диктофон.
Кстати, диктофон не очень пользуется популярностью. Иногда лучше попросить эксперта написать, как получится, а технический писатель потом прочитает этот материал, сделает красиво и задаст вопросы, которые у потенциального джуна в команде тоже возникнут.
Так документация становится понятнее, технический писатель глубже погружается в доменную область, а команда разработки снимает с себя нагрузку, связанную с тем, что нужно отвечать на вопросы по этому функционалу.
Ревью и оформление от команды технических писателей
После того как они оформили документацию, мы возвращаем её в команду разработки на ревью.
Ревью эксперта от команды реализации
Независимо от того, писали мы по постановке задачи от аналитика или по черновику от разработчика, мы отдаём материал эксперту на ревью. У меня был опыт, когда документацию отдают не тому эксперту, который консультировал или писал, а другому. Это даёт возможность человеку свежим взглядом взглянуть на код и убедиться, что он написан верно. Он в процессе ревью погружается в ту часть кода, которую не писал. Так мы обеспечиваем взаимозаменяемость людей внутри команды.
Но это культура, которая должна быть сформирована на достаточном уровне, чтобы такой подход заработал. Тогда экспертом, который дает ревью, становится автор черновика или человек, который работал по постановке.
Ревью от смежных команд — опционально
Мы используем ревью от смежных команд в случае, если хотим отдать эту документацию какой-нибудь команде.
Был классный кейс, когда мы пришли к девопсу и спросили, что написать про сервис, чтобы он мог взять его на поддержку 24/7 и не имел права звонить разработчику ночью. Вот так мотивация! Сначала он долго формулировал, какие именно документы нужны и в каком виде. Но когда мы всё это подготовили, он проверил их очень тщательно — ведь на входе уже была чёткая постановка задачи. То есть сразу были требования к документации и цель найти время на ревью.
Но для технических описаний ревью — это часть процесса разработки. Документация прописана как финальный этап подготовки. В таком случае задача считается невыполненной до тех пор, пока не написана документация.
Здесь мы ещё играем с тем, что в параллель может работать — как мы должны сократить какие-то затраты на что-то. Но главная идея в том, что нужно вписать это в процесс и понимать, что в каждом спринте у вас будет время, которое вы потратите на документацию. Если у вас его не будет, к сожалению, хорошей технической документации у вас не будет никогда.
Есть примеры, когда мы назначаем, условно, сколько нужно потратить SLA на ревью, и получаем формальный подход к этой работе. У человека реально не было времени на проведение ревью, а SLA поджимает.
Поэтому вы должны быть готовы ещё и к тому, что спринт ограничен: вы заложили в него какой-то объём задач, и раньше конца спринта никого никак не пушите. Иначе получите весьма формальный подход к тому, как будет проведено ревью.
Что делает эксперт при проведении ревью
Экспертом может стать ведущий разработчик или юрист, финансист и т.д. в зависимости от типа документации. Любой человек, если он в конкретной теме — суперспециалист.
Вероятно, проверяет документацию он нечасто. Чтобы ему помочь, можно предложить чек-лист ревью:
Достоверность описания — не наврали ли вы, пока формулировали красиво.
Очень часто мы пытаемся переформулировать, и формулировка получается пограничная. То есть, трактовать её можно двояко, а это недопустимо. Нам нужна верифицированная трактовка, которую нельзя прочитать иначе.
2. Достаточность глубины изложения — всё ли мы учли.
Какую задачу решаем, до куда будем копать, какова глубина, подходящая для решения конкретной задачи и т.д. Здесь часто возникают споры. Иногда кусок текста переезжает в другую документацию, или наоборот, мы дописываем большие куски, связанные с мелкими нюансами.
При этом вы в п��становке говорите: представь, что ты хочешь рефакторить этот код. Если нужно ещё что-то — напиши, чтобы мы понимали, чем дополнить.
3. Корректность формулировок — не переврали ли мы названия инструментов и другие термины.
Если мы говорим о юристах — там отдельная песня. Если мы говорим об HR, это тоже супер-песня. Если у нас есть Tone of Voice, а это документация, которую мы покажем наружу — надо убедиться, что он соблюдён.
Помощь в формировании списка триггеров обновления
Что такое список триггеров? Как помним, в требованиях у нас есть актуальность. Я открываю доку, и если она опубликована, то она актуальна. Так вот, список триггеров — это те события, по которым я начну проверять актуальность контента, связанного с этим триггером.
Лучше, чем разработчик, никто не расскажет, что может измениться и когда стоит проверить актуальность описания. Сначала, возможно, придётся уговаривать. Но со временем он поймёт профит, и этот процесс станет естественным — я вас уверяю. Продаётся идея легко: «Ты не будешь отвечать на вопросы сутками». Вначале некоторое время он будет кидаться в ответ на тупые вопросы ссылками, а потом его перестанут трогать. Люди просто осознают, что вместо километра текста им отправят ссылку, куда посмотреть.
Пользовательская документация
Этого типа контента сейчас в Maxim Technology нет, но я участвовала в подготовке такого контента, когда работала с сопровождением.
Под пользовательской документацией мы понимаем руководство пользователя, раздел часто задаваемых вопросов в открытой части сайта и прочее, где юзер, не обращаясь в саппорт, может получить информацию о вашем продукте.
Готовит технический писатель
Я пока не видела кейса, где бы её готовил не техпис. Говорят, что бывают волшебные аналитики, но я не встречала.
Ревью ведущих экспертов по теме
Мы уже говорили про чек лист для эксперта. Для пользовательской документации эксперт даёт ревью по этому чек-листу, а дальше документация отправляется на ревью в команду сопровождения.
Ревью команды сопровождения
Очень часто этого этапа нет, но никто лучше саппорта не знает, что ломается чаще и какой стандартный кейс пользователь может починить сам. Это не означает, что с такими вопросами перестанут ходить в саппорт. Будет часть пользователей, которые всё равно дочитают и не пойдут, и ваши затраты на ответы на эти вопросы снизятся на 15−20%. Это зависит от вашего объёма — иногда это супер-ощутимый выигрыш.
Документация сопровождения
Это мой любимый зоопарк. Отдельный вид искусства, который включает в себя, например:
Шаблоны ответов на обращения пользователей
Зависит от спектра вопросов, которые могут задать. Классно, если вы просто техническая поддержка. А если вы ещё на на все вопросы отвечаете…
Инструкции по устранению аварий для пользователей и инженеров сопровождения, иногда начиная с первой линии.
L1 — отдельная моя любовь, — напрямую общаются с пользователями. Я их обожаю за то, как они любят людей и всё ещё никого не убили. Отдельное мое почтение с точки зрения того, что я уже очень давно не слышала ответ поддержки в стиле «отвали от меня». Для них есть всякие инструкции, для L1 довольно жёсткие — их нельзя дополнять и действовать не по ним. Если стандартная инструкция не работает, мы передаём на L2.
L2 очень хочет снизить нагрузку, и поэтому эти инструкции — очень замороченная тема. Знаю, что говорю, потому что имела отношение к базе знаний первой линии.
Какие задачи решает документация сопровождения:
Готовит специалист сопровождения
Я уверена в том, что никто лучше специалиста саппорта не напишет доку для саппорта — он знает, как пользователь задаёт вопрос и формулирует описание проблемы.
У нас была история, когда Минцифры сказало, что нужно руководствоваться нормативно-правовыми актами страны. Слово «скриншот» нигде не поименовано, но есть волшебная формулировка «снимок экрана». Представляете, какие вопросы прилетали от пользователей, когда ему говоришь: «Представьте мне набор снимков экрана 1, 2, 3», и он… фотографирует свой экран. Но нельзя по-другому спросить.
Никто не напишет документацию так, чтобы пользователи начали всё понимать и при этом быть политкорректным с точки зрения требований по формулировкам.
Ревью коллеги
С одной стороны, это позволяет коллеге глубже погрузиться. Например, если вы занимаете пограничные зоны — он отвечает за один сервис, вы за другой, и даёте ему ревью по соседнему сервису. Тогда в момент, когда у вас случится пожар, вы смогли бы из соседних сервисов в помощь забрать людей.
Ревью даёт возможность быть в теме и посмотреть на свою работу со стороны пользователя, так как человек не особо погружён и будет делать ровно так, как ему сказали, не додумывая. А глубокая погружённость — это история про додумывание.
Ревью эксперта
Это необходимо, чтобы соответствовать требованиям нормативно-правовых и внутренних актов, не переврать функционал и не перепутать фичу с багом.
Максимально частая история — помню, мы написали очень длинную инструкцию, а потом аналитик сказал, что это баг, завёл тикет и аннулировал инструкцию. А мы её примерно неделю писали всей командой L2, тестируя на тестовом стенде. Она воспроизводится везде, мы её очень подробно написали, чтобы всем было понятно, интересно и здорово! А оказалось, это просто баг.
Это надо отсеять на входе, потому что проблема массовая. Если бы мы не привлекли аналитика, то мы бы отдали в контактный центр, и это было бы плохо.
Понятный алгоритм внесения правок и публикации дополнительных версий
Отдельно поясню про дополнительные версии. У нас были шаблоны ответов со ссылками на нормативно-правовые акты. После правок правительства новые формулировки могут вступить в силу 1 января — в максимально неудобное время для внедрения изменений в контактном центре.
У меня была страница, в которой были версия до 1 января и версия с 1 января. Это решало проблему того, что я не буду 31 декабря в 23 часа передавать контактному центру новую версию, а более интересным займусь. Нужно продумать, что учесть.
Если вы верифицируете контент каким-то зверским способом, то нужно фиксировать вопросы и ответы сразу, и понимать, что это ещё не прод. Но есть формулировка вопроса и формулировка ответа. А ещё мы не уверены в том, что это достаточно корректный ответ, чтобы опубликовать новую версию.
Как в этой ситуации жить, тоже очень важно подумать, чтобы человек не забыл и из контекста не выпал. Я использую комментарии по тексту: выделяем кусок и навешиваем на него комментарий.
Итого
Если с базой знаний что-то не так — неудобный поиск, устаревшие или повторяющиеся материалы и т.д., а люди приходят с одинаковыми вопросами, — мы не посыпаем голову пеплом, а решаем вопрос через организацию работы. Чем поможет ревью документации:
Внутреннее ревью — прокачивает команду и делает документ более полным, последовательным, понятным.
Мы учимся друг у друга. У меня и сейчас в команде есть джуны, которые перенимают опыт у более опытных коллег. Не секрет, что нет такого вуза, который бы выпускал на выходе технических писателей, поэтому техпис — это особый сорт специалистов, которых нужно ещё уметь прокачать, а внутреннее ревью как часть такой способности.
Я пришла к тому, что джун тоже может дать ревью, и иногда лучше, чем синьор.
Ревью ведущего эксперта — прокачивает команду экспертов и позволяет растить новых, а также гарантирует достоверность, достаточную глубину и точность документа.
По сути, прокачиваем экспертизу и софты, как дать обратную связь так, чтобы не отбить руки написавшему.
Обратная связь от пользователей документации — помогает лучше учесть запросы.
Это задача с двумя звёздочками. Она позволяет улучшить документацию так, чтобы потенциальный пользователь нашёл все ответы, которые планировал найти в контенте такого типа.
Скрытый текст
А чтобы узнать больше информации, переходите на сайт «Онтико» и следите за анонсами новых конференций — в этом году вас ждет много интересного!
