Привет! Меня зовут Аня Салугина, я технический писатель в Ozon Tech. Наша команда готовит и актуализирует документацию для покупателей, продавцов, партнёров, разработчиков и сотрудников Ozon. Недавно мы решили, что хотим улучшить наш стайлгайд и сделать его публичным.
Эта статья — рассказ о том, как мы это сделали: искали новую структуру, обсуждали спорные моменты с командой и запускали обновлённый стайлгайд в работу.
Спойлер: командная работа — ключ к успеху
Шаг 1. Анализируем старый стайлгайд и отмечаем его минусы
Мы не начинали с чистого листа — стайлгайд у нас уже был, и мы активно им пользовались. Чтобы не просто сделать стайлгайд публичным, но и улучшить его, мы выделили основные проблемы, над которыми предстояло поработать:
стайлгайд местами устарел, а некоторые правила переходили в виде комментариев из вычитки в вычитку;
не было выделенного ресурса на поддержание стайлгайда в актуальном состоянии;
по стайлгайду было сложно ориентироваться — практически все правила лежали на одной странице и не в самом логичном порядке.
Шаг 2. Формируем новую структуру стайлгайда
Сначала я прочитала наш стайлгайд от начала до конца и отметила спорные или устаревшие моменты. Это был небольшой квест: нужно было разобраться, какие правила ещё работают, а какие уже неактуальны. Понять, что правило потеряло актуальность, было легко — таким правилам мы больше не следовали. Например, от текстов от имени Ozon мы плавно перешли к текстам от первого лица.
Затем из того, что было актуально и важно, следовало составить новую структуру. Мы хотели сделать её более логичной и последовательной. Для этого нужно было выделить основные логические группы, к которым относятся наши правила, и вынести их в будущие основные разделы.
Чтобы это сделать, сначала я посмотрела стайлгайды других компаний и их структуру — все они были совершенно разные. Например, в одних стайлгайдах все правила хранятся на одной странице под абстрактными заголовками, а в других собраны в слайд-шоу в Figma и имеют более строгую структуру. Было очевидно: стайлгайды не пишутся по шаблону, и в них тоже проявляется TOV компании. Например, в обращении к читателю и выборе лексики.
Стайлгайды и редполитики, которыми я вдохновлялась:
Затем я выписала существующие разделы нашего старого стайлгайда на стикеры и разложила их по логическим группам. Так родились 2 главных раздела: «Написание документации» и «Оформление документации». Позже расскажу подробнее о каждом из них.
Шаг 3. Актуализируем и дополняем стайлгайд
После утверждения новой структуры мы взялись за обновление содержания. Здесь началось самое интересное: часть правил можно было легко перенести из старого стайлгайда в новый, но некоторые вопросы нужно было прояснить с командой, чтобы прийти к общему правилу. Например:
В каких случаях мы используем табы?
Как лучше написать: «Нажмите Добавить» или «Нажмите на кнопку Добавить»?
Нужен ли поясняющий текст перед списком, если его свойства выполняет заголовок?
Мы собирались с командой на созвонах, обсуждали вопросы и вместе искали лучший вариант. Один из самых жарких споров у нас был про оформление маркированных списков. В итоге в разделе Оформление документации у нас появился целый подраздел, посвящённый спискам. После созвонов я обязательно записывала итоги встреч, чтобы не забыть, к чему мы пришли, потому что рассмотрений было много.
Если бы не совместные переговоры, вокруг многих решений мы бы ещё долго ходили кругами. Общие созвоны не только помогли принять более взвешенные решения, но и повысили доверие внутри команды. Во-первых, наша команда состоит из людей с самым разным бэкграундом — они охотно участвовали в обсуждениях и делились своим опытом. Во-вторых, коллеги видели, что их мнение действительно важно.
Подробнее о наших разделах
Мы выделили 2 главных раздела: «Написание документации» и «Оформление документации». В раздел «Написание документации» вошли правила о стиле текста, грамматике и пунктуации. В раздел «Оформление документации» — рекомендации по форматированию текста и использованию визуальных элементов.
Раздел «Написание документации»
Голос и тон
Сначала я думала, что у технической документации не может быть тона и голоса, ведь это тексты, лишённые всякой эмоции, главная цель которых — донести информацию до пользователя. Но оказалось, что нет! В процессе командных обсуждений и сравнения нашей документации с документацией других компаний мы поняли, что у нашей справки есть тон — нейтральный и обучающий. Наш голос — вежливый и сдержанный, но не формальный.
Мы заботимся о пользователе, не влияем на его восприятие и объясняем сложные вещи простым языком. Наша документация — как заботливый коллега, который мягко подскажет, как использовать инструмент или совершить действие.
Всё это мы отразили в статье «Голос и тон».
Слова и названия элементов интерфейса
Если вы на досуге читали стайлгайды других команд, наверняка встречали в них глоссарии — мини-словарики с терминами и определениями. Мы решили, что в таком понимании глоссарий нам не нужен, ведь мы почти не используем в документации сложные узконаправленные термины. Если они и попадаются, то мы даём им определения сразу в статье. Поэтому мы составили список слов, с которым можно свериться, чтобы проверить их написание, и к употреблению некоторых оставили комментарии.
Также в этот раздел вошли названия и описания элементов интерфейса. Здесь, среди всего прочего, мы отметили, что для краткости и простоты не используем слова «кнопка», «чекбокс» и «тогл».
Орфография, пунктуация и символы
Название говорит само за себя: здесь объяснили, где поставить дефис, а где — тире, как оформлять номера телефонов, писать числительные и сокращать единицы измерения. Конечно же, начали с того, что всегда пишем букву «ё», если в слове она есть.
Синтаксис
Это раздел о составе предложения и порядке слов в нём. Здесь отразили нашу любовь к активному залогу и отметили, что цель действия лучше упомянуть в начале предложения. Поясню: представьте, что вы читаете инструкцию, в которой предложение звучит так: «Откройте файл и перейдите на вкладку Пользователи, а затем нажмите на пользователя и выберите Удалить, чтобы заблокировать его». Теперь представьте, что вы в принципе не собирались блокировать никакого пользователя и потратили драгоценное время, чтобы прочитать целое предложение и только в конце узнать, зачем оно нужно.
Раздел «Оформление документации»
Структура документации
Здесь описали, из чего состоит статья: названия, описания и заголовков, — как выглядят разводящие страницы разделов и что на них можно разместить.
Ещё посчитали важным описать правило составления заголовков: никаких «как» и вопросительных формулировок. Мы уверены, что главная мысль заголовка — действие — следует сразу после вопросительного слова. Например, из заголовков «Как зарегистрироваться на сайте», «Как добавить друзей» и «Как удалить аккаунт» можно легко выбросить «как». Заголовки от этого ничего не потеряют, а станут только компактнее, и пользователю не придётся тратить время, чтобы найти решение своей проблемы среди бесконечных «как».
Оформление текста
В этом разделе описали, как оформить текст в списки, ссылки и таблицы. До того как мы описали оформление списков в нашем стайлгайде, на эту тему у нас было больше всего обсуждений и споров. Как расставить пунктуацию в маркированном списке, а как в нумерованном? А что делать, если пункты списка слишком длинные? Нужен ли поясняющий текст перед списком, если его роль может выполнить заголовок? Ответы на все эти вопросы (и не только на эти) собраны в данной статье.
Визуальные элементы
Здесь описали инструменты, которые помогут визуально разграничить информацию в статье — табы, цветные плашки, скриншоты и раскрывашки.
У каждого из инструментов есть своё строгое предназначение. Например, мы используем разные цвета плашек для разных видов информации, а табы используем только для тех случаев, когда перечисляем несколько способов совершить одно и то же действие.
Шаг 4. Внедряем новый стайлгайд в работу и отмечаем результаты
Когда новый стайлгайд был готов, я представила его команде: подготовила короткую презентацию, где прошлась по всем разделам и рассказала, где что лежит. Теперь в пару кликов можно найти, как оформить текст в таблице или какую цветную плашку использовать.
Через пару недель после релиза я отправила коллегам опрос, где собрала обратную связь по поводу наполнения и структуры стайлгайда. Коллеги отметили, что с новой структурой стало проще ориентироваться по стайлгайду и искать информацию. Также многие обрадовались, что мы наконец сформулировали правила, которых в старом стайлгайде не было.
Нам стало заметно проще обсуждать вопросы стиля. Например, фраза «посмотрите в гайде» стала универсальным аргументом в рабочих спорах. Раньше мы говорили: «кажется, это есть в гайде», и не всегда информация оказывалась там в актуальном виде, а теперь на стайлгайд можно положиться. А главное — он стал реальным инструментом, которым приятно пользоваться и можно делиться с другими.
Шаг 5. Поддерживаем стайлгайд в актуальном состоянии
Так как мы активнее ходим в стайлгайд, мы стали чаще замечать, что какой-то информации в нём не хватает. Почти каждый спринт мы добавляем какие-то новые правила или дополняем существующие.
Кроме того, у нас появился человек (я), ответственный за актуальность стайлгайда; к нему (то есть ко мне) можно прийти с вопросами или попросить добавить в стайлгайд что-то новое. Кроме того, я знаю наполнение стайлгайда практически наизусть, поэтому меня всегда можно призвать в тред и спросить, отражено определённое правило в стайлгайде или нет, или пригласить поучаствовать в споре в качестве авторитетного лица.
Чем чаще ко мне приходят с вопросом, тем насущнее он становится и тем быстрее мы создаём тикет на доработку стайлгайда. Например, один из таких вопросов — использование жирного начертания в тексте. Когда мы его используем, а когда нет? И почему сложилось именно так? Нам ещё предстоит сформулировать это правило.
После того как создаём тикет на доработку стайлгайда, его может подхватить любой желающий из нашей команды. И это здорово, потому что так мы не замыкаем все процессы на одном человеке.
Выводы
Краткое резюме всего, что было рассказано выше, или tl:dr:
Сначала анализ, потом работа. Мы выявили проблемы стайлгайда, с которыми предстояло поработать, и вопросы, которые вызывают у нас больше всего споров. После этого проверили актуальность существующих правил.
Новая структура. Приятно пользоваться документом, в котором всё разложено по полочкам.
Актуальное содержание. Устаревшие правила, которые больше не соблюдаются, могут привести к спорам и недопониманию в команде, а стайлгайд может потерять свой авторитет. Наличие специального человека в команде, который отвечает за обновление и поддержание стайлгайда, помогает поддерживать актуальность документа.
