Меня зовут Ирина Исай, я техническая писательница, или техрайтерка, киберспортивного медиахолдинга WePlay Esports. Хочу поделиться своим опытом аудита технической и подготовки продуктовой документации сразу для нескольких продуктов компании, в которой работаю сейчас. Эта история будет охватывать и опыт из моих предыдущих проектов – там тоже было много интересного и полезного.
Моя история сотрудничества с WePlay Esports, частью холдинга TECHIIA, началась именно с такой задачи: провести аудит документации. За прошлый год я не раз слышала от разных компаний о желании его сделать. Одни хотели нанять техрайтера на полный день, чтобы провести аудит и после этого внедрять разработанные рекомендации, другие – только проконсультироваться о процессе.
Поэтому приглашаю менеджеров команд, техрайтерив, продакт-оунеров провести вместе следующие 15 минут. Поговорим об аудите технической и продуктовой документации: что это, зачем и как лучше его проводить. Тема свежая и мало исследованная – ее обсуждают в статьях и комментариях техрайтерського сообщества не очень активно.
А еще приглашаю к разговору команды разработчиков и тестировщиков. Если вас бесят техрайтеры, которые постоянно что-то твердят о документации, отрывают от работы, допрашиваются, где ваши заметки, пытаются заставить вас что-то где-то задокументировать, возможно, здесь вы найдете ответы на свои вопросы или подсказки, как наладить сотрудничество с ними.
Наш разговор имеет целью уравновесить две жизненные несправедливости:
- Не существует правил или стандартов, по которым должен происходить аудит документации. Материалов на эту тему в сети – минимум. Не потому, что кто-то ленивый или жадный на опыт и знания. Просто сфера IT в целом очень изменчива: все подходы и процессы меняются с такой скоростью, что не успеешь закончить инструкцию или рекомендацию, как уже нужно писать новую. Надеюсь, мой опыт облегчит жизнь, а может, и вдохновит тех, кто собирается взяться за это нелегкое дело.
- Команды и руководство компании не считают аудит документации чем-то крайне необходимым, откладывают его до лучших времен. Многие вообще не слышали о нем. Даже само слово «аудит» воспринимают негативно: это некая «проверка» работы, поэтому команды относятся несколько враждебно к такому вмешательству. Будет хорошо, если мои размышления изменят ваше отношение.
Аудит документации
Начнем с определения терминов.
Аудит продуктовой и технической документации – это комплексная проверка имеющейся документации на предмет актуальности, достоверности, полноты, соответствия определенным стилям и другим предварительно установленным критериям и требованиям. Цель эксперта или команды, которые ныряет в такой аудит, – оценить текущее состояние дел, определить, чего не хватает, и предоставить необходимые для устранения недостатков рекомендации.
Аудит документации необходимо проводить с определенной регулярностью. Обязательно должна быть привязка к периоду – возможно, раз в версию или при смене менеджмента, стратегии развития или перезагрузки команды. Многое зависит от интенсивности развития продукта и определенных целей аудита. Обычно эта задача идет от топ-менеджмента и является одним из этапов аудита всех продуктов компании. Но случается, что потребность в аудите определяет сам техрайтер или команда, с которой он работает, предварительно очертив четкие цели.
Нередко слышу: «Зачем тратить столько времени и денег на документирование? У нас и так все работает».
Вот несколько причин.
Онбординг. Если вменяемой документации у вас нет, это может означать, что куски экспертизы и информации о продукте держатся в мозгах отдельных людей. Времени поделиться с новичками своими знаниями они часто не имеют.
Поэтому вместо того, чтобы заставлять новых сотрудников бегать по офису от стола к столу с кучей вопросов, лучше иметь структурированный гайд, где будет подробная и актуальная информация. Во-первых, гайд сделает онбординг мягким: люди скорее схватят информацию о продукте и связи между продуктами, если их несколько. Во-вторых, снимет огромную нагрузку с продакт-оунеров.
Продажа или привлечения инвестиций. Кроме вменяемого онбординга, компании иногда интересуются продажей, партнерством, привлечением инвестиций. Потенциальному инвестору или партнеру недостаточно внешней картинки и обещаний, что все работает. Он должен понимать, как все устроено изнутри. А для этого нужно иметь соответствующую документацию, которая четко и интуитивно понятно описывает продукты и их функциональные аспекты.
Зачастую бывает, когда описываешь продукт постфактум, находится какой-то функционал, о котором никто даже не догадывается и не может объяснить, откуда он взялся и как оно работает, потому что никто не документировал его создания. Такой функционал может годами жить в продукте. А это значит, что на экране всегда будет незаметная кнопка или лишняя строчка в форме, которые в лучшем случае не имеют никакого функциональной нагрузки.
В общем, качественно подготовлена документация – это лицо продукта компании и (не) лишнее подтверждение ценности самой компании. Также это знак качества работы каждого специалиста, задействованного в проекте, и команды в целом.
Стандарты и подходы к аудиту документации
Мой небольшой опыт в аудите документации показал, что это комплексный процесс со многими неизвестными. Я долго изучала информацию в сети и сделала неутешительный вывод: стандартов и четких правил до сих пор не существует. Но есть best practices. Они основываются на индивидуальном и коллективном опыте техрайтеров и их команд.
Конечная цель команд, которые разрабатывают продукт, и техрайтера, который занимается аудитом – не убить друг друга до завершения аудита. Я даже уверена, что создать эти стандарты и рекомендации все-таки возможно. Коллективный разум – великая сила.
Этапы и временные границы
Надо быть готовым, что аудит и дальнейшая работа над внедрением его рекомендаций займут от нескольких недель до нескольких месяцев. Условно весь процесс можно разделить на следующие этапы:
- Изучение имеющейся документации. В основном она техническая и зачастую неактуальна.
- Разработка рекомендаций для устранения недостатков. Их, кстати, никто не читает, поэтому лучше представить устно с хорошей визуализацией.
- Начало работы с продуктом. Изучение самого продукта и разработка стандартов к его описанию происходят параллельно.
- Разработка единого стандарта написания технической документации для всех команд. Это опциональный пункт: его не избежать, если это крупная компания, где работает много разрозненных команд. При этом каждая команда имеет своего техрайтера, и все вынуждены сами вести свою техническую документацию.
- Формирование культуры техрайтинга в компании. Это моя профессиональная заветная мечта. Знаю случаи, когда команды не воспринимали техрайтера как кого-то важного и нужного.
Следовательно, не надейтесь, что вся эта история закончится быстро. Вот как было у меня.
Первый месяц. Техрайтер собирает абсолютно все документы, записи, читает каждый гайд, словарь, политику, если таковые имеются. Задача – изучить то, что есть, найти «дыры» в последовательности, выявить неактуальное, разработать план упорядочения того, что можно упорядочить.
Так я составляла Audit Summary. Пробелы, структура, язык написания, заголовки, стиль или его отсутствие – все, что могло быть важным, расписывала по пунктам.
Второй месяц. Когда все хоть немного прояснилось и стало понятно, насколько «пациент жив», можно перейти к лечению локальных болячек — сконцентрироваться на конкретном проекте (продукте) или на конкретном участке (команде).
Здесь уже можно начинать составлять рекомендации по написанию новой документации, собирать терминологию и тому подобное. Из своего опыта скажу, что даже в одной команде люди могут по-разному подписывать один и тот же функционал: на английском, рунглише, транслитерацией из всех возможных языков мира. А еще команды любят аббревиатуры — это вообще отдельная история извращений.
Черновик инструкции для техрайтеров: я люблю сразу определять «правила игры» и всегда говорю по пунктам — так пишем, так не пишем. Объяснения не расписываю, обсуждаем и согласовываем все устно. Далее идет некий чек-лист для техрайтера — только самое главное.
Третий месяц. Как только мы выяснили, каких стандартов и подходов не хватает, и начали описывать их, уже имеем определенный план действий.
Напомню, это нужно, если у вас несколько команд, а вы один-единственный техрайтер и физически нет возможности писать техническую документацию для каждой команды. Поэтому наша цель — помочь командам вести свою документацию хорошо, а главное — стандартизировать подходы. Так мы облегчаем жизнь всем.
На этом этапе большая часть продуктовой документации верхнего уровня уже проработана и сведена к единому стилю, пробелы заполнены, неактуальная информация удалена и собрано немало данных обо всех продуктах, которые используют в следующих статьях.
А это коротенькое вступление к большому мануалу, который будет состоять из гайдов, которые будут состоять из статей... Но не это главное, и даже не содержание, — содержание еще изменится не раз. Главное, что им уже может пользоваться любой желающий. Люблю структурировать так: вступительное слово, о чем документ; содержание; разделы; дополнительные ссылки на смежные статьи выношу в конец материала.
Четвертый месяц. Стандарты написания технической документации уже понемногу внедрены — можно дополнительно провести учебные сессии для команд. Итак, время стандарты корректировать.
Да, вы прочитали правильно. Зачем корректировать то, что только создали?
Потому что все команды разные. Уровни восприятия, доверия, в конце концов желание что-то изменить в своей работе тоже разные. Нельзя загнать всех в одну клетку. Но можно унифицировать подходы, чтобы всем было удобно и понятно, как работать. Кроме того, уже можно финализировать «хвосты», которые остались с третьего месяца.
А если у вас несколько команд и несколько продуктов, которые между собой еще и объединены в определенных процессах, все эти четыре месяца приходится сидеть на шпагате. Отсюда на первом этапе возникает определенная сумбурность: невозможно предсказать, какой получится структура продуктовой документации, какими будут названия статей, даже то, какими должны быть их визуальные компоненты. Каждая компания, как и ее продукты, очень индивидуальны.
Не каждая команда радуется аудиту документации
В идеальном мире команды, только создав новый продукт или фичу, обращаются к техрайтеру с запросом описать новое решение. От этого выиграют все: команды получают буквально письменное подтверждение своей работы. Хоть в резюме записывай: вот, что я создал, вот, как это работает. Компания видит, из чего состоит ее продукт, «чувствует» его. А техрайтеру многого не нужно — удовольствие от правильного описания. Ценник всех трех сторон, поверьте мне, только растет от проактивности команд.
В реальном мире приходится все описывать «на вчера» и ежедневно преодолевать преграды.
Будем откровенны, никто не хочет взваливать себе на плечи дополнительную задачу, какой бы благородной ни была ее цель. На моей практике были команды, которые пытались любой ценой отделаться от «ненужной» формализации процессов, лишних расспросов, даже были случаи полного игнора.
Дело может осложниться, если техрайтер еще и не находится физически в одном помещении с командами. А сегодня, когда бушует пандемия и мы все работаем удаленно, контакт сводится к кнопке «отправить сообщение».
Мое решение — искать единомышленников.
Невозможно уговорить людей скучными заверениями, что должен быть порядок и все от этого порядка выигрывают. Но возможно заинтересовать, показать, что инвестировать немного их времени и внимания сейчас — это сэкономить часы, и даже недели усилий совсем скоро.
Сразу в список потенциальных «сторонников» можно вносить продакт-оунеров, бизнес-аналитиков, проектных координаторов. Они обычно очень заинтересованы в том, чтобы в продукте все было разложено по полочкам. Конечно, предварительно нужно ознакомиться, «продать» им идею аудита документации так, чтобы они жили его преимуществами, пропагандировали как добро среди своих команд.
Также обязательно боритесь за любовь и внимание тестировщиков и разработчиков. Они — источник интересной информации о продуктах, а если повезет, еще и хранители ценной технической документации.
В разговорах с возможными союзниками я акцентирую на том, что качественная документация — это дополнительная ценность команды и каждого специалиста. Наиболее частые возражения следующие:
- «Наша ценность — это продукт, который мы создали». Согласна. Но для стороннего наблюдателя это комплексная «обертка» с логотипом компании, за которой не видно работы конкретных экспертов.
- «Наша ценность — это написанный код». И снова согласна. Но в основном похвастаться кодом можно только перед теми, кто его понимает, и только если это не запрещено договором о неразглашении. Внешне же код почти никто не видит и не разбирает.
В обоих случаях документация — возможность показать себя. А если она содержится в свободном доступе, для команды это возможность обосновать свои умения и навыки.
Иногда техрайтеру понадобятся и софт скилы, иначе говоря, народные методы: вытащить нужного человека на прогулку / пиво / танцы. Это помогает настроить вас на одну волну.
А дальше — как в мелодраме. Команды к вам, как к техрайтеру, уже привыкли, хотя вы их продолжаете иногда раздражать. Тапочками не бросаются — уже хорошо. Еще немного времени — и сбудется мечта техрайтера: они сами придут с предложениями что-то описать в документации. А если они не забыли позвать вас на свои встречи-груминги, то это уже любовь!
Onsite-аудит vs outsource-аудит
Аудит документации, как и любой другой, могут проводить как внутренние, так и внешние эксперты. Конечно, здесь есть свои преимущества и недостатки, но единственно правильного решения не существует: все зависит от того, какие цели определило руководство.
К тому же не все компании могут себе позволить держать команду техрайтеров. А иногда внешняя консультация нужна, чтобы усовершенствовать определенные процессы или просто перенять новый опыт.
Внешний аудит — это незамыленный взгляд на документацию и возможность получить актуальные рекомендации для команды техрайтеров. Даже если у компании нет техрайтера, это шанс стандартизировать документы, а следовательно, повысить ценность продукта. Однако внешний аудит — это еще и риск разглашения информации об интеллектуальной собственности компании.
Для техрайтера провести аудит в другой компании — это тоже немалые преимущества: от изучения новых процессов до совершенствования своих навыков.
Внутренний аудит документации — явление редкое. Если честно, я не слышала, чтобы кто-то его проводил. Конечно, не в счет крупные компании с международным опытом, для которых такие процессы — обычное дело. Как по мне, если компания позволила себе иметь техрайтера или даже целую команду, то внутренний аудит документации должен быть обязательным, проводиться с определенной регулярностью и по определенным процедурам.
(Не)финансовый результат
Понимаю тех, кто хочет измерить качество и ценность аудита документации в деньгах. Но здесь прямой связи с доходами нет.
Впрочем, вот вам, например, контрольные вопросы. Сколько может сэкономить/ заработать компания от того, что:
- команда не будет тратить время на то, чтобы вводить новичков в курс дела, знакомить с продуктом в целом, рассказывать подробно о каком-то функционале, а потратит эти часы или даже дни на непосредственные обязанности (код, тестирование, релиз т.д.)?
- новый человек в команде быстрее ознакомится с продуктами компании, элементарно узнает, где можно найти необходимую информацию об уже созданном функционале?
- снизится ли нагрузка на службу поддержки, найдут ли пользователи нужные ответы в документации?
- команды будут иметь дополнительную информацию о том, как работает продукт их коллег из других команд (смежного функционала или продукта), а следовательно, согласуют и унифицируют процессы по взаимосвязанным проектам?
Список вопросов можно продолжить, ведь каждая команда и компания получит свою ценность от такого аудита. А ответ на них один: хорошо описанная документация значительно облегчает жизнь всем вовлеченным в создание и поддержание продукта сторонам.
Кроме того, на мой взгляд, аудит документации именно сейчас приобретает актуальность. Вокруг бурлит пандемия, мир вступает в новый финансовый и экономический кризис, компании вынуждены переосмысливать свои процессы и стратегии развития. Аудит документации здорово помогает этому переосмыслению, возможно, даже станет источником поиска стратегически важных решений.
А ваша компания проводит планирует провести аудит документации? Как это происходит у вас?
