Привет, меня зовут Наталья, я мобильный QA Engineer вот уже более 6 лет. Занимаюсь как мануальным, так и авто-тестированием, успела поработать в стартапах и в крупных компаниях. Однако везде, где мне доводилось работать, была одна и та же боль – документация. А если быть точнее, ее скупость или отсутствие как таковой. И на каждом новом месте мне приходилось быть тем, кто ее пишет.
Magnit Tech не стал исключением, ведь я пришла в команду, которую только-только сформировали. То есть – ни одной странички в Confluence в нашем разделе.
Звучит пугающе? А меня это заинтересовало. Так что, в этой статье я расскажу:
Зачем –> определение конечной цели
Кому –> распределение ответственности
О чем –> выбор темы для документации
Когда –> выбор времени для написания
Как –> эффективное донесение информации.
А также поделюсь двумя вариантами подхода к написанию документации + как работать над стилистическим оформлением.
Сама документация бывает разной – черной, белой, красной. Но всем нам очень хочется, чтобы она хотя бы была, ведь факт её присутствия на проекте дарит спокойствие и некую уверенность в завтрашнем дне. В идеале, конечно, чтобы она была всеобъемлющей, своевременной и понятной каждому, верно?
Казалось бы, да, все и так всё прекрасно понимают: если тебе нужна дока – берешь и пишешь ее. Однако, когда дело действительно доходит до написания – тут то и начинаются проблемы. Почему? Давайте разбираться.
И для начала мы определимся:
Зачем писать документацию?
Простота – достаточно скинуть ссылку чтобы исчерпывающе ответить на текущий вопрос и дальнейшие потенциальные
Повышает автономность сотрудников
Облегчает жизнь интровертам – требуется меньше коммуникации, ведь все необходимое зафиксировано в тексте
Уменьшает временные затраты на решение проблем – быстрый поиск необходимой информации
Облегчает процесс онбординга новичков - дает чувство безопасности и стабильности т.к. «на каждый мой вопрос есть ответ/дока, я знаю где и что посмотреть». Когда документации нет или она не очень хорошо расписана это вызывает чувство тревоги, беспокойства, бесконечные хождения по коллегам.
Сохранение экспертизы - проще дописать еще пару пунктов в доку, чем начинать ее с нуля когда ничего нет.
Разгрузка головы – кратковременная память, как правило, не может запомнить и повторить более 7 ± 2 элементов – а дока помнит всё.
Уникальность и ценность на рынке труда – на собеседованиях редко кто-то говорит, что любит и умеет в документацию (подтверждено десятком моих собеседований)
Кому нужно писать документацию?
Всем и каждому
Если скилл написания документации развивает только один член команды – этот сотрудник становится «незаменимым», «единственным кто может», т.е. на него подвязывается очень многое.
Потеря такого сотрудника – очень болезненный удар. И потерять его можно не только увольнением: повышаются риски выгорания.
Пример: мое выгорание
Мне очень нравится изучать что-то новое и структурировать полученную информацию в визуально приятном формате – тексте. Так что я довольно быстро стала единственным человеком в команде, который пишет документацию – онбординг для новых QA, фиксация договоренностей с другими командами, гайды, графики, таблички и т.д.
Коллектив быстро привык к такому положению вещей. Ни у кого не возникало вопросов, кто напишет следующую доку, ведь это, как обычно, буду я.
Человеческий ресурс имеет свойство заканчиваться и я достигла предела при работе над большой докой. В какой-то момент просто не осталось сил - ни моральных, ни физических. Я словила выгорание и отказалась работать с текстом в принципе. Я просто не могла этим больше заниматься.
К чему это привело — доку так никто не дописал, не актуализировал. По сути, она была попросту заморожена до тех пор, пока я не "вернусь обратно".
Во избежание подобных ситуаций, важно, чтобы каждый развивал скилл написания документации как внутри команды, так и в целом в компании.
О чем писать документацию?
Обо всем (что болит)
Любая документация должна закрывать чью-то боль. Желательно вашу в том числе, ведь это отличный стимул для ее написания. Если вам было больно и приходилось буквально "добывать" информацию – доку нужно написать. Даже если в моменте это кажется какой-то мелочью – доки разные нужны, доки разные важны. Сборник мини-заметок по теме может быть очень полезным. Никогда не знаешь, кому еще он может помочь, кроме тебя. К тому же, чем меньше нужно держать в голове, тем легче дышать и думать.
Пример: Terminal на M1
При тестировании очень часто приходится ставить сборки на девайсы. Со времен работы на Windows я привыкла использовать для этого терминал, тем более, когда нужно поставить релиз-кандидат сразу на несколько устройств – вбил команду, Enter, подождал, стрелка вверх, снова Enter. И так необходимое количество раз.
Однако, при трудоустройстве в Magnit Tech мне выдали MacBook, за которым ранее я практически не работала. В процессе так же выяснилось, что есть нюансы установки Homebrew, если у тебя процессор на M1. Пришлось покопаться, чтобы найти решение проблемы.
Разобравшись, я записала небольшой гайдик в Confluence себе на всякий случай, но, как оказалось, он потребовался и моим коллегам – тем, кто так же впервые работал на M1.
Вот так, казалось бы, "незначительная заметочка для себя" спасла несколько сотен нервных клеток у моих коллег :)
Когда нужно писать документацию?
Сразу, здесь и сейчас
«Не ждите «подходящего момента», его никогда не будет. Начинайте там, где стоите, и работайте с теми инструментами, которые есть в вашем распоряжении, — по мере продвижения обнаружатся и лучшие»
(с) Брайан Трейси
Велик соблазн сказать себе «потом»: когда наконец зарелизимся, вот закрою таску и возьмусь, в пятницу вечером расчищу себе окно и т.д.
Однако, очень легко впасть в прокрастинацию, если привыкнуть к этому слову. Чаще всего это самое «потом» превращается в обыденное «никогда». Доки не пишутся, знания не закрепляются, не передаются коллегам (разве что по-старинке – из уст в уста) и, как следствие, теряются, забываются, уходят в небытие. Начинается эпоха стагнации (в лучшем случае).
По этому доки нужно писать сразу при столкновении с болью – хотя бы накидать список вопросов, рыбу, структуру, план действий при решении той или иной задачи.
Почему сразу: в дальнейшем ответы будут полностью или хотя бы частично найдены, даже если поначалу будет казаться, что «ну тут что-то супер сложное». К тому же в процессе записи вопросов могут так же стремительно найтись и ответы. А получив ответы, будет проще их зафиксировать в уже созданную ранее страничку в Confluence. Затем можно попросить помощи у коллег, дополнить пропуски и белые пятна.
Как итог: появится исчерпывающая документация, закрывающая боль
Пример: TestRail -> Allure TestOps
Наша компания долгое время использовала TestRail для тестирования. Однако, с желанием автоматизации, так же пришло понимание, что нужен другой инструмент и выбор пал на Allure TestOps – имеет лучшую интеграцию с автотестами, хорошая документация, API, активное сообщество, нет влияния санкций и т.д.
Никто ранее с ним не работал, так что, вполне закономерно, начались проблемы.
Тем не менее, мы быстро накидали базовую доку с основными положениями/организационными моментами/договоренностями в моменте по этому инструменту и пошарили на всю QA-гильдию. В дальнейшем просто продолжали дополнять то, что уже есть и причесывать "шероховатости".
Таким образом, освоение нового инструмента в нашей компании прошло быстро и почти безболезненно для всех QA.
Какие могут возникнуть проблемы:
Страх чистого листа.
Решение: Запись только для себя – создать приватную страничку в личном пространстве Confluence и закидывать туда все заметки, причесывать их и структурировать. Писать «для себя» психологически проще, чем «для всех» – снижается груз ответственности. А к моменту, как наберется достаточная «масса» – можно будет расшарить коллегам/перенести в рабочее пространство.
«Я не потяну в соло».
Решение: Коллеги – попросить помощи, договориться разделить работу, записывать ваш диалог в процессе/ответы на вопросы если нет уверенности в своих компетенциях. В дальнейшем – попросить ревью.
Синдром самозванца.
Решение: Разрешить себе ошибаться. Каждая ошибка - кирпичик опыта, из которого строится карьера синьора. Нет ничего страшного в том, чтобы поделиться знаниями с коллегами. Это ведь просто опыт, а не трактат «Как правильно жить эту жизнь».
Я тоже ошибалась и знаю, как тяжело порой бывает это принимать. Однако, если посмотреть в перспективе – все ошибки были найдены и устранены, ничего не взорвалось, а я получила бесценный профессиональный опыт.
Итак, с «Когда» определились. Что дальше?
Как правильно писать документацию?
Помнить, что каждый аспект имеет значение
«Идеал недостижим, но совершенствование заключается в стремлении к идеалу»
(с) Николай Римский-Корсаков
Ключевые аспекты для качественной документации:
Логичное расположение в проекте
Выстроенная структура/структурированное изложение
Лаконичное оформление/стилистика
Простота текста/читаемость для целевой аудитории
Картинки
Итог: высокий уровень усвоения информации
Естественно, чем больше внимания уделять каждому из них – тем лучше будет итоговый результат. Однако нельзя забывать про человеческий фактор – объяснить всё, всем и каждому на 100% не получится. Нужно просто принять это как факт.
Когда же мы, наконец, садимся писать техническую документацию – вспоминаем, в каком огромном чане с информацией находимся. Разрозненные куски, взятые из совершенно разных источников: теоретическая база, таски в спринте, дизайн-макеты, слова коллег, заметки, наши собственные мысли. И все это у нас в голове одновременно. Тут порой даже думать бывает тяжело, что уж говорить про выжимку текста для доки по теме?
В таком случае есть два стула основных подхода к написанию: структура и масса
Вариант 1 (структура):
Максимально упрощаем и сокращаем то, что хотим донести
Создаем структуру - обозначаем общие блоки и выстраиваем хронологию, порядок, расположение
Постепенно заполняем блоки
Делаем чай
Пьем чай (опционально)
Финальный проход по всей доке целиком с начала и до конца — дописываем необходимое
Отправляем на ревью коллегам
Этот вариант отлично подходит для больших док или дерева документации.
Например как это было у нас:
Появился запрос на погружение в автоматизацию всех продуктовых команд – от настройки Android Studio до своего первого MR. Команда Platform имела экспертизу по автотестам – они взялись лидить это направление. И наша команда AppTech должна была стать «первопроходцем» в плане обучения, по сути это была обкатка по передаче знаний/экспертизы. Проба пера в наставничестве. Однако, по автотестам у нас ничего не было. Вообще ничего. Совсем.
Понимая, какой большой пласт информации предстоит освоить – я предложила создать дерево документации по Android-направлению автотестирования.
Это была самая сложная работа/часть во время обучения. Ведь по сути мне пришлось записывать каждый свой шаг и каждое решение возникающих проблем.
Благо, с самого начала я поняла, что нужно сразу разбивать всю поступающую информацию на логические блоки. Делать на каждый такой блок страничку в Confluence, а затем расписывать то, что знаю, самостоятельно. Оставшиеся пробелы и шероховатости подхватили/оформили коллеги из Platform.
Естественно, получилось не идеально и было много проблем на пути формирования этого дерева. Однако все усилия окупились – другим продуктовым командам было гораздо проще "въехать" в автотесты. Им было достаточно просто идти по доке в хронологическом порядке, чтобы в итоге сделать свой первый MR в develop.
Это и было то, к чему мы изначально стремились. Это успех, девочки.
P.S. позже по образцу так же оформили iOS-направление.
Вариант 2 (масса):
Записываем весь поток из головы напрямую, каждую мысль, относящуюся к теме, наращиваем ту самую «массу»
Делаем чай
Читаем
Создаем структуру - обозначаем общие блоки и выстраиваем хронологию, порядок, расположение
Постепенно заполняем блоки
Снова делаем чай
Финальный проход по всей доке целиком с начала и до конца
Отправляем на ревью коллегам
Как можно заметить по количеству чая – второй вариант вкуснее. За это я его и люблю :)
Кстати если в процессе написания у вас вдруг появились мысли для какой-то другой или смежной темы - нужно обязательно их разделить. Одна дока - одна тема.
Итак, ключевые моменты усвоили, с выбором подхода определились. Что дальше?
Стилистическое оформление
Мало написать доку, нужно чтобы она работала
(с) Хорошилов Даниил, лид QA-комьюнити Magnit Tech
Стилистика это очень важно, ведь текст может быть сколько угодно полезным, но если он нечитаем – все усилия впустую. Поэтому я ориентируюсь на эту статью при вёрстке текста.
Кстати Википедия – неплохой пример оформления для документации + гиперссылки на другие страницы как еще одна хорошая практика в копилку.
Так же вы всегда можете попросить фидбэк и помощь в оформлении у коллег, подсматривать, как они оформляют свою документацию и брать лучшие практики. Про это написано много статей на Хабре — например, супер-подробный и полезный гайд по проектированию в Confluence от коллег по цеху, за что им огромное спасибо ^^
Ревью документации
Я довольно часто сталкивалась с игнорированием этого важного пункта. После написания, доку, в лучшем случае, показывали парочке коллег. Чаще всего — не показывали никому, как бы оставляя ее «дрейфовать в Confluence». Такой подход не эффективен, особенно если мы говорим про большую работу — дерево документации по автотестам, описание новых подходов и т.д.
Качественное ревью — один из ключевых аспектов качественной документации. Но как же его получить?
В нашей компании мы используем итеративную раскатку 1-2-5-50. Что это означает?
Когда на проект внедряется что-то новое, будь то технология или инструмент, то требуется обкатка через early adapter’ов — коллег, которые имеют достаточный уровень экспертизы и «пощупают» новинку первыми. Этот подход мы можем применять и при работе с документацией.
Тут план такой:
Показываем
Собираем фидбэк
Вносим правки
Повторяем цикл
В каждом цикле увеличивается кол-во early adapter’ов для раскатки: 1-2-5 и далее хоть все 50.
В итоге, после прохождения всех необходимых нам циклов, мы получаем качественную документацию на проекте и, как следствие, более качественный продукт. Тем более если экстраполируем этот опыт на всю компанию.
Поддержание актуальности
Итак, вот мы зафиксировали в доке все тонкости и нюансы, причесали текст, прошли ревью. А потом все изменилось. Или не все, а только часть. Что делать? Естественно актуализировать. Но кто будет это делать?
Тут аналогичная история как и с написанием – в идеале, чтобы каждый член команды имел возможность (и способность) сразу актуализировать, если что-то устарело или поменялось.
Таком образом будет повышаться «живучесть» нашей документации на проекте.
Гласность
Помимо написания и оформления документации нужно еще не забыть о ней рассказать. «Минуточку, а зачем? Написать – написал, в проект положить – положил. Коллеги ведь не маленькие – сами найдут!».
Увы, но нет. Сообщить о существовании доки так же важно как и написать ее.
Например у нас на проекте произошла, казалось бы, невозможная ситуация:
При слиянии департаментов произошло вливание команд в основной проект. Тестировщики нового направления решили заняться автоматизацией, но из-за дискоммуникации, некоторого хаоса от переезда и человеческого фактора, ребятам не показали доки по автоматизации, т.е. информация была упущена. По этому они были вынуждены писать заметки, в которых была плюс минус та же информация, что и в нашем дереве по Android. Им пришлось писать все буквально с нуля. Елена (имя выдумано, ситуация – нет), как одна из таких «первопроходцев» в автотестировании, составила большую доку с описанием проекта, его настройкой и другими полезными мелочами.
Выяснился этот момент достаточно поздно. Конечно, в итоге мы объединили наши доки в единое целое. Однако, было потрачено несколько недель на работу, которая, по сути, была вхолостую.
Уведомлять своих коллег о доках важно и нужно – вовремя кидать их им на ревью, подсвечивать в гильдиях, тэгать потенциально заинтересованных и т.д. Это в разы облегчит передачу экспертизы и снизит вероятность недопонимания.
Итоговая мысль
Документацию нужно писать каждому. Иначе получится ситуация, когда этот скилл развивает только один член команды, что чревато плачевными последствиями – коллега может выгореть, заболеть, покинуть компанию, при этом поддерживать старую и писать новую кто-то должен. А скиллов нет/не хватает и что тогда? ХАОС, АД, АРМАГЕДДОН. Шучу. Просто жребий на написание, по закону подлости, выпадет вам. Так что, лучше подготовиться заранее, верно? :)
Написание документации – важный скилл для всех. Это должно стать привычкой.
Столкнулись с болью – записали. Решили – дописали.
Качественная и актуальная документация это всегда плюс (к карме и к зарплате).
