Метаморфозы сознания. Про ревью и комментарии в технической документации
Привет! Меня зовут Дмитрий Миронюк, я старший технический писатель в компании Bercut. До этого работал системным администратором, специалистом внедрения и поддержки, программировал IP-телефонию, успел поработать тимлидом. Но как в итоге стал техническим писателем расскажу в другой раз. Сегодня поговорим о ревью и комментариях. Приведу реальные примеры из личного опыта, а также поделюсь наблюдениями, как процесс ревью повлиял на мое сознание.
Причем тут метаморфозы
Метаморфоза — процесс превращения или переход из одной формы в другую. В биологии гусеница превращается в бабочку, то есть полностью меняет форму своего тела и его функции. В геологии известняк под воздействием некоторых природных факторов превращается в мрамор. Но изменение формы и физических свойств не являются обязательными факторами метаморфозы. Сознание человека тоже постоянно меняется — появляются новые привычки, меняются убеждения, принципы и поведение. Такой процесс называют «метаморфозы сознания» или «изменение мышления».
На наше сознание влияют разные факторы: новые законы, новые друзья, другие страны, профессии или хобби. Недавно я обнаружил, что одним из таких факторов является привычный процесс ревью. Мы получаем новые знания, когда обрабатываем комментарии к своей работе. Обмениваемся опытом, когда изучаем творение автора и обсуждаем решения по улучшению его работы. При этом не важно, что является артефактом, будь то техническая документация, программный код, схема развертывания системы или статья на Хабр. Главный ингредиент — это правильно сформулированный комментарий. Но как писать замечания, чтобы не навредить и не отбить мотивацию у автора? Расскажу об этом чуть позже. Для начала вспомним, что такое ревью и почему этот процесс так популярен в IT-компаниях.
Что такое ревью и так ли оно необходимо
Представим, что перед нами стоит задача испечь большую пиццу диаметром 40 см. Назовем ее «Фантазия». На выходе должна получиться пицца с тонким слоем теста, богатой начинкой и запеченной корочкой сыра. Но готовить будем не сами — наймем пекаря. Если первая попытка приготовления завершится неудачей, то доставку новых ингредиентов придется ждать несколько дней. И пекарю нужно будет заплатить за отработанные часы. Одним словом, потерпим убытки. Поэтому важно минимизировать вероятность ошибки.
Первым делом найдем опытного пиццемейкера и подробно расспросим о процессе приготовления. На основании полученной информации напишем следующие документы:
справочник ингредиентов,
требования к оборудованию,
инструкцию по приготовлению.
Ну что, все входные данные есть, приступаем к готовке? Не стоит рубить с плеча. Давайте подумаем, какова будет цена ошибки, если мы допустим неточность при описании процесса, например, укажем не ту температуру и время запекания. Тогда наша «Фантазия» подгорит, а еще хуже — сломается оборудование или случится пожар. А если пекарь из-за ошибки в справочнике смешает ингредиенты для приготовления теста не в тех пропорциях, тогда смеси не получится придать правильную форму и сделать бортики. Думаю, ни первый, ни второй исход нас не устроит. Поэтому нужно исключить ошибки в документах. В этом нам помогут несколько этапов ревью.
Ревью — это процесс проверки текста, кода или другого артефакта. Цель проверки — выявить ошибки или неточности и указать на них автору. Проверяющего называют ревьюером или рецензентом. Обычно ревью проводят в несколько этапов, так как рецензентами должны быть люди разных направлений. В случае с «Фантазией» первым проверяющим может выступить наш коллега. Его задача примерить на себя роль читателя, для которого был написан документ. Он оценит, насколько просто мы представили информацию, нет ли двусмысленности в словах и фразах, логично ли построен текст и структура документа.
На следующем этапе проверяет пиццемейкер. Он выполнит ревью с экспертной точки зрения — укажет на неточности в процессах и справочниках, подскажет, какую информацию нужно убрать или добавить. Возможно, мастер во время интервью что-то забыл рассказать. Все эти пробелы будут видны в тексте, а эксперт поможет их дополнить.
Последним этапом проводит ревью пекарь — человек, для которого предназначается документация. Обычно эту роль называют «стейкхолдером». Он оценит, достаточно ли информации, чтобы справиться с задачей приготовления пиццы. Представленные инструкции и справочники в документе не должны вызывать у стейкхолдера вопросов.
Пример с «Фантазией» весьма показательный, но в IT все немного сложнее. Наша компания разрабатывает сложные системы для операторов связи. Документацию читают инженеры и пользователи заказчика, а также наши разработчики, тестировщики и специалисты поддержки. Если текст будет написан сложно, без структуры, единого стиля, схем и скриншотов, то никто не станет его читать — проще заявку оставить или спросить напрямую. В итоге получим финансовые убытки — зря потраченные трудозатраты (ТЗ) технических писателей, дополнительные ТЗ техподдержки и время экспертов, которых будут отвлекать вопросами.
Еще хуже наличие ошибок и неточностей в документации. Тогда специалисты заказчика неправильно настроят какую-нибудь функцию, и миллионы абонентов столкнутся с проблемами. Возможно, кому-то нужно сделать важный вызов, связанный с безопасностью людей, а счет номера телефона окажется заблокированным. Такого допустить никак нельзя. Если перед публикацией провести несколько этапов проверки документа, то мы избежим подобных инцидентов. Именно поэтому процесс ревью в нашей команде является неотъемлемой частью разработки технической документации.
Как составлять комментарии
Главный инструмент процесса ревью — это комментарии. С помощью них рецензент и автор общаются, не выходя за рамки документа. Ревьюер вычитывает текст и оставляет замечания. Автор обрабатывает полученные советы и переделывает документ, либо оставляет как есть, аргументируя свою точку зрения.
Пример текста:
Здесь явно видно, что предложение составлено с нарушением. Нужно написать замечание автору, и сделать это мы можем по-разному. Вот некоторые варианты:
Пишешь ты скверно, конечно, какой из тебя технический писатель…
Функционал? Ты серьезно?
Нельзя здесь использовать слово функционал, это грубейшая ошибка!
А как бы написали вы?
Посмотрим на пример хорошего комментария:
Чем же хорош такой комментарий?
Ревьюер составил замечание в позитивном ключе и, помимо того, что указал на ошибку, объяснил, как нужно написать правильно и почему. Такой комментарий вызовет только положительные эмоции, и автор документа запомнит, что слово «функционал» некорректно использовать в данном контексте.
Опираясь на свой опыт, опыт коллег и пройденные курсы, я выделил следующие правила комментариев процесса ревью:
Указываем не только на проблему, но и предлагаем решение. Такой подход позволяет сократить время на дополнительные вопросы.
Пример 1.1:
Пример 1.2:
Опираемся на правила русского языка или общепринятый Style Guide компании, а не на свое субъективное мнение.
Пример 2.1:
Пример 2.2:
Всегда пишем с уважением и никаких оскорблений!
Пример 3.1:
Добавляем позитивное подкрепление — отмечаем успешные моменты, хвалим автора. Если все время делать только замечания, то можно погубить уверенность.
Пример 4.1:
Пример 4.2:
Иногда может быть полезным и субъективное мнение, как читателя.
Пример 5.1:
Пример 5.2:
Также хотел бы упомянуть про реакцию автора на комментарии. Часто бывает, что люди не готовы принимать критику. Они пишут такие фразы, как «сам дурак», «у тебя не лучше» или вообще шлют куда подальше. С таким отношением процесса ревью не получится. Поэтому для ответа на замечания лучше придерживаться следующих правил:
Благодарим респондента за проверку. Это важно. Ведь он потратил время и энергию ради нас.
Отвечаем конструктивно: согласны с замечанием — ставим знак »+», не согласны — приводим свои аргументы.
Не принимаем все правки, советы и замечания бездумно: прорабатываем каждый случай, возможно ревьюер ошибся.
Если я не согласен или сомневаюсь с предложенными советами ревьюера, то в ответе на комментарий ставлю »!!!». После обработки документа, нахожу по ключу »!!!» в поиске все противоречивые комментарии и назначаю ревьюеру встречу. Мы созваниваемся, обсуждаем выделенные вопросы и приходим к общему решению. Если вопросов один-два, и они требуют только короткого пояснения от респондента, то я пишу в чате личное сообщение. Такой подход позволяет сократить время на переписки в комментариях документа и быстро решить возникшие вопросы.
Как устроен процесс ревью в нашей команде
В Bercut у технических писателей процесс ревью проходит в несколько этапов, которые выполняются параллельно друг другу. За исключением самого последнего — отгрузки документа заказчику. Ревью состоит из следующих этапов:
Опытные коллеги — технические писатели проверяют структуру документа, опечатки, возможные технические ошибки, формулировки и схемы. Проверяют получены ли в документе ответы на следующие вопросы:
Читатель понимает о какой системе идет речь, и как система работает?
Читатель с помощью документа выполнит необходимые настройки системы и разберется с ошибками ее работы?
Редактор проверяет большую часть того же, что и технический писатель, но плюс к этому еще несколько моментов:
Стилистику — соответствует ли формат текста общепринятому Style Guide компании.
Грамотность — соблюдены ли правила русского языка.
Двусмысленность и смысловое значение — отсутствие сложных словесных форм и предложений.
Соответствие правилам упрощенного технического русского языка.
Эксперты по системе — аналитики, разработчики, тестировщики, инженеры проверяют текст на соответствие техническому описанию системы.
Прием документа заказчиком.
Этапы 1, 2 и 3 выполняем параллельно. Автор отправляет документ на проверку сразу нескольким ревьюерам. Получив замечания и советы, редактирует текст и отправляет еще раз редактору.
Перед отправкой заказчику документ может пройти несколько итераций этапов 1–3. Словно алмаз, мы доводим каждый артефакт до финала, вытачиваем грани, шлифуем небольшие неровности и в конце — полируем до яркого блеска. Такая схема проверки технической документации позволяет нам держать качество разрабатываемых документов на высоком уровне.
Как процесс ревью повлиял на мое сознание
Слово «метаморфозы» в названии статьи я использовал не случайно. Но не для того, чтобы привлечь внимание модным словечком. Я заметил, что процесс ревью приводит к изменению мышления. При этом не важно, кто выступает ревьюером. Каждый оставленный комментарий — это обмен опытом между людьми. А любой человек имеет свой уникальный и ценный опыт.
Недавно обнаружил, что теперь я повсюду замечаю искаженные смыслы и канцелярский язык. Мысленно представляю, как бы написал по-другому. Например, объявление о запуске отопления, которое размещала управляющая компания (УК) на двери подъезда моего дома:
Я когда прочел, сильно негодовал! В пятиэтажках типа «Ленинградка» система отопления построена так, что в некоторых квартирах есть задвижки, которые перекрывают стояк по всем этажам. На лето УК просят закрыть задвижки. А с подачей отопления, пока жители таких квартир не откроют задвижки, горячая вода по трубам остальных квартир не побежит. На улице холодно уже несколько дней, люди ждут тепла, отопление давно запущено, ну почему не написать вот так:
Уважаемые жители квартир № ХХ, ХХ, ХХ!
Откройте задвижки на стояках.
Отопление подано в дом 25 сентября.
К 4 октября температура теплоподачи будет увеличена — ТЭЦ выйдет на рабочие температуры.
Вся информация уместилась в 4 строки. Зачем в объявлениях писать такие фразы, как »в связи с постановлением Администрации»,»произведен запуск» или »для полноценного запуска»? Убираем канцелярит и текст становится простым, понятным и кратким.
Когда супруга пишет посты в свой блог, я непроизвольно нахожу в них избыточность местоимений, деепричастных оборотов или смыслов в одном предложении. В таких случаях не могу удержаться и отправляю жене новый переделанный вариант. В результате, она сама того не замечая, обретает новые навыки письма. И с кажым разом ее тексты становятся лучше.
Даже в обычной рекламе теперь я вижу искаженные смыслы. Пример:
Случайно где-то увидел, прочел и понял, что это просто «кровь из глаз». Написано так, будто предлагают способ по растяжению тела, а в придачу и плохое самочувствие. На самом деле это лишь неудачная формулировка. Может быть написать вот так:
Растяжка мышц всего тела
Получите 40 онлайн-тренировок, вместо абонемента в зал. Воспользуйтесь безопасным гайдом по стретчингу в домашних условиях. Мышцы вашего тела расслабятся, уйдут зажимы, улучшится самочувствие и координация движений.
Я вижу, как растет мой навык написания текстов. На одних только курсах и рутинной практике такого бэкграунда я бы не получил. Бустером выступает именно процесс ревью. Когда-то, еще до Bercut, я работал IT-инженером. Помимо основных задач писал инструкции для пользователей, специалистов техподдержки и системных администраторов. Но никакой обратной связи не получал. Поэтому искренне полагал, что пишу как профи. Смотрю сейчас на эти тексты и ужасаюсь.
Думаю, аналогичная ситуация наблюдается в процессе ревью кода и технических проектов. Разработчик, аналитик или архитектор вырастет кратно быстрее, если предоставит свои артефакты на проверку и получит обратную связь от коллег. С каждым новым полученным комментарием и советом будут появляться новые идеи. Со временем сознание начнет меняться, специалист освоит новые подходы, методы и техники. А количество повторяющихся ошибок сойдет на нет.
