стайл гайды что это
Теперь сапожник с сапогами, или Как у нас появился свой стайл гайд
Предполагаю, что вам, уважаемые читатели, в своей работе доводилось иметь дело с технической документацией и, возможно, даже с теми, кто ее создает — с техническими писателями. А в нашем блоге вы могли познакомиться с техническим писателем из команды Veeam.
Сегодня переходим на следующий уровень понимания того, как устроена разработка технической документации в Veeam Software.
КДПВ обманчива — никакое это не чудо, а такая же работа, как и у всех остальных коллег из R&D. Однако у тех, кто создает гайды, есть волшебные слова свои гайды по созданию гайдов! Вот такая вот рекурсия.
Подробнее — в рассказе моей коллеги Дарьи Шалыгиной.
Привет, меня зовут Даша, и я Content Quality Lead в компании Veeam Software. Я отвечаю за качество контента, создаваемого отделом технических писателей нашей компании. Практически, я технический писатель и редактор в одном флаконе. В мои обязанности входит:
Время шло, компания росла, продуктов становилось все больше, и возникла необходимость в увеличении штата технических писателей. Сегодня нас уже 18 человек, и мы не планируем на этом останавливаться. Все бы хорошо, но внезапно оказалось, что при таком количестве человек договориться о прекрасном становится трудновато. Требуется время, время и еще раз время.
Чтобы сократить энергозатраты на передачу знаний вновь прибывающим, а также чтобы раз и навсегда зафиксировать, что есть «прекрасное» в технической документации Veeam, было принято решение создать наш собственный стайл гайд. Нужно сказать, что какие-то наметки на тему стиля уже существовали многие годы у нас в виде статей на Confluence и заметок на полях в блокнотах, но все это было неупорядоченно, разрозненно, и, конечно, ни о какой простоте использования и актуальности информации говорить не приходилось.
Когда мы создавали наш стайл гайд, мы взяли за основу 3 крупных гайда, которые обычно принято брать за образец при написании документации: (Chicago Manual of Style, Microsoft Manual of Style и DITA Best Practices), изучили ряд сторонних стайл гайдов, существующих у других компаний (например, IBM Style Guide, Documentation Style Guide for OpenSolaris и другие), провели исследование последних тенденций в области документации — и смешали все это с нашим собственным одиннадцатилетним опытом работы в Veeam Software.
В итоге в Veeam Technical Writing Style Guide вошли такие злободневные темы, как структурирование контента по типам топиков, принципы Plain English, пунктуация, артикли, форматирование, оформление скриншотов и диаграмм, оформление ссылок на собственную и стороннюю документацию, а также полезные напоминалки на каждый день.
С появлением стайл гайда мы не только облегчили процесс передачи знаний новым сотрудникам, но и получили следующие преимущества:
Известный мем о том, как разительно меняется стиль письма после того, как вы поработали техническим писателем
Наш стайл гайд был создан не-носителями английского языка (non-native speakers) и предназначался для не-носителей же. Тем не менее, он был вычитан и выверен нашими коллегами-носителями (native speakers), лингвистами из отдела Marketing, которые имеют соответствующее образование, уже давно пишут тексты для сайта компании, и у которых разработан собственный стайл гайд, также основанный на принципах упомянутых гигантов отрасли.
Сейчас мы работаем над расширением нашей базы знаний. Мы хотим создать отдельные стайл гайды для справочных документов, таких как REST API Reference и PowerShell Reference. Для таких документов контент нужно структурировать особым образом, и это необходимо зафиксировать в целях поддержания единообразия между продуктами.
Мы будем рады, если наш стайл гайд будет полезен другим компаниям, которые пока еще только находятся в поисках собственного стиля. Советую еще посмотреть на раздел со справочной информацией, которая, по нашему опыту, частенько бывает нужна в работе — там много интересного. 🙂
Стайлгайд или руководство по стилям
Jul 30, 2018 · 2 min read
Очень часто получая макет на верстку я не находил там одного очень нужного файла — руководства по стилям или по другому стайлгайда.
Всякий раз мысленно чертыхаясь и коря такую работу, я думал о том, почему дизайнер поленился сделать этот файл и сколько времени на выяснение тех или иных нюансов мы бы съэкономили.
Причины по которым дизайнеры не хотят делать стайлгайд бывают разные, банальная лень, отсутствие опыта и профессионализма, жадность — зачем я буду тратить на это свое время, если мне за него не платят.
Хотя я считаю, что стайлгайд необходимо делать по умолчанию и точка.
Зачем он нужен?
Если п роект большой и над ним трудиться несколько человек то стайлгайд это единое руководство по стилю для всего проекта, так дизайнерам гораздо проще придерживаться единых правил по выбранному стилю. Во вторых, его наличие гораздо упрощает процесс разработки в дальнейшим и снимает огромное количество вопросов от верстальщика и программиста.
Что должен содержать в себе грамотно составленный стайлгайд:
Дизайнер обязан продумать и показать каждый вариант, и то как будет выглядеть элемент во всех состояниях.
Это минимум того, что должно быть показано в руководстве по стилю.
В идеальном варианте хотелось бы видеть как будут отображаться всплывающие окна, сообщение об ошибках на странице, блоки с подсказками для пользователя. Чем проще и доступнее вы объясните элементы макета, тем будет проще верстальщику понять и воплотить задумку при сайта. Не ленитесь, работайте с умом и на совесть, тогда с вами будет приятно работать другим.
Бонусом вы можете посмотреть как могут выглядеть руководства по стилю для больших проектов:
Стайл гайд это руководство по стилю, сопроводительная документация к дизайн макетам страниц. Здесь есть все стандартные элементы и компоненты дизайна, а также шрифты, размеры изображений, в некоторых случаях разметки сетки (если она не стандартная и важна логика отступов в блоках). Эти элементы и блоки необходимо использовать в процессе верстки и в дальнейшем, на сайте.
Что входит в стайл гайд?
Цветовая палитра
Для каждого проекта цветовая палитра создается индивидуально, и состоит из 10 основных цветов; бывают ещё нейтральные (например, для фона плашек) и вспомогательные. Ключевые цвета используются во всех макетах проекта. Иногда, когда проект большой и цветов много, для удобства создаются группы цветов с общим названием по назначению.
Типографика и текстовые блоки
В хорошей типографике все читаемо и все “на своих местах”. От выбора шрифта зависит удобство чтения и то, насколько пользователь задержится на сайте. В типографике необходимо продумывать шрифтовые пары и описывать правила применения тех или иных заголовков, а также отображать их вес в соотношении друг к другу.
Инпуты
Нужно максимально полно отображать все состояния полей для ввода и выпадающих списков. Это поможет пользователю во взаимодействии с сайтом и упростит ему поиски нужной информации.
Компоненты
Элементы, повторяющиеся на всем сайте, в Figma превращаются в компоненты, а затем просто копируются по страницам: ссылки, кнопки, меню, чекбоксы и радиобаттоны и другие элементы дизайна. В свою очередь, компоненты могут иметь несколько вариантов отображения элемента.
Сетка макета
В основном, в проектах используется сетка bootstrap, но существует множество других. Сетка позволяет выровнять и логически выстроить элементы и контент на странице будущего сайта. Использование сетки позволяет адаптировать десктопную версию в мобильную версию сайта при дальнейшей разработке.
Модальные окна
Важно указать стилевое решение для всех модальных окон, состояние ошибок при заполнении, правильно заполненные поля.
Описание анимации
Анимация описывается в комментариях к макету страницы или же прилагается отдельный документ с примерами взаимодействий для того или иного блока элемента текста слайдера.
Что такое Style Guide? Как создать руководство по стилю?
Что такое Style Guide – алгоритм создания
StyleGuide – это адаптированная система, содержащая элементы и правила, подходящие под стилистику определенного сайта. Основное назначение – создание единого стилистического направления и целостности дизайна. Это необходимо не только разработчикам, но и дизайнерам, которые участвуют в процессе создания сайта. Для реализации проекта важно заручиться поддержкой специалистов. Создание определенного гайда направлено на разработку единого стиля. Важно продумать каждый этап, учитывать особенности сайта и на основании этого подбирать формы, оттенки и т.д. Правильно реализованная задача – залог качественного конечного 🔥 результата.
Основное назначение руководства по стилю
Руководство по стилю – это сопроводительный документ, который предоставляется к дизайн-макетам страниц сайта. Наличие такой инструкции направлено на легкость считывания и верстку страниц с соблюдением «индивидуальных» правил. Руководство содержит информацию о стандартах оформления интерфейса системы. Здесь есть все, от внешнего вида интерактивных элементов, до шрифтов, изображений и даже логической разметки страницы.
Стайлгайд – это справка с набором стандартов и требований, обязательных к соблюдению. Их необходимо использовать в процессе оформления сайта. Ключевое назначение – создание единого стилистического и оформительского однообразия. Наличие инструкции поможет при развитии 💡 продукта, а также в случае доработки существующей функциональности.
Как создать руководство по стилю?
Создать Style Guide можно по определенному алгоритму. В процессе разработки инструкции, необходимо учитывать следующие параметры:
Цветовая гамма
Подбор оттенков осуществляется в индивидуальном порядке. Палитра должна иметь ряд цветов, с учетом особенностей самого сайта. Все оттенки условно разбиваются на нейтральные, основные и вспомогательные. На данном этапе необходимо определиться и с цветовыми решениями для кнопок.
Каждый оттенок имеет свой персональный код. И это очень удобно при верстке ⌨️ страниц и создании дизайна. В инструкции важно указать не только коды оттенков, но и их общее процентное соотношение.
Важно! Не забывайте выделять ключевые области и расставлять акценты. Это способствует концентрации внимания потенциальных клиентов.
Типографика
Типографика – это качество, которое сразу видит посетитель, посещающий сайт. От выбора шрифта зависит успех сайта. И это вовсе не шутка! Приятный шрифт располагает, а яркие и несуразные буквы вызывают желание скорее покинуть ресурс. В типографике важно продумать каждую деталь и описать 📝 правила применения определенных шрифтов. Это касается заголовков, основного текста и общих размеров.
Важно! Правильно оформленный сайт требует логической завершенности. Если типографика применена неграмотно, у посетителей это вызовет ряд негативных эмоций. Оформление всегда должно быть понятным и четким.
Компоненты
Данный раздел должен содержать типы кнопок, которые будут использоваться в процессе создания сайта. Дополнительно указываются ссылки, чекбоксы, чекбаттоны и другие инструменты, которые способствуют ведению конструктивного диалога с пользователем.
Компоненты нужны для создания привычного и стандартного элемента дизайна сайт. Это очень и очень важно! От правильности подбора компонентов зависит коммуникация пользователями с сайтом.
Важно! Кнопки и ключевые элементы должны подталкивать пользователя к определенному действию.
Текстовые поля
В разделе с текстовыми полями должны отображаться все возможные состояния полей ввода, выпадающие 📃 списки и т.д. Указанный блок содержит и равномерность. Оформление в едином стиле должно подталкивать пользователя к определенному действию.
Важно! На сайте должны быть только значимые поля. Таким образом возрастает вероятность заполнения клиентом нужной формы. Не забывайте о четком выделении ошибок.
Иконки
В разделе с иконками содержатся мини-изображения со всего сайта. В инструкции указывается стиль их изображения, а также сам значок сайта. Иконки позволяют извлечь максимум со всего дизайна сайта и при этом они несут максимальную пользу. Главная задача иконок – предоставление подсказок 💬 пользователю и облегчение навигации по сайту. Согласно показателям информативности, это самый полезный инструмент.
Важно! При выборе дизайна иконок необходимо ориентироваться на целевую аудиторию. В учет берется менталитет, увлечение и даже культурно-историческое развитие. Использование указанных факторов позволит избежать фатальных ошибок.
Логотип
В разделе «Логотип» содержаться правила его использования. В обязательном порядке отображаются цветовые сочетания, а также соотношение отступов и строк. В разделе «Логотип» указывается расположение, методы работы с фоном, а также список разрешенных и запрещенных оттенков. Обязательно учитывается межбуквенное расстояние и т.д.
Важно! Задать параметры логотипа очень важно. Ведь именно он отвечает за формирование персонального стилистического направления сайта. Логотип отвечает за тон всего сайта и действительно задает настроение
Главные «НЕ» для логотипа:
Сетка и отступы
В хорошем проекте используется бутстрап-сетка. Она позволяет выровнять все составляющие ресурсы. Это очень важно! Особенно в процессе создания общей концепции стайлгайда. Более того, использование сетки и отступов позволяет ⚙️ адаптировать ресурс для мобильных устройств, планшетов и других гаджетов.
Использование сетки – это соблюдение всех пропорций, без постоянного вычисления параметров и расстояний. С этой целью необходимо заложить базовые закономерности и построить сетку. При создании общей концепции, необходимо просто придерживаться установленной сетки.
Важно! Дизайнерские макеты содержат 12-колоночную сетку. В некоторых случаях возможны исключения.
Модальные окна
В этом разделе содержаться все модальные окна, применимые для конкретного портала. Дополнительно указывается стилистика, а также удачные и ошибочные состояния.
Важно! Информации, которая отвечает за целевое действие (заказ, покупку, регистрацию) необходимо уделить особое внимание. Благодаря им происходит взаимодействие клиента с сайтом.
Анимация
Для загрузки страниц затрачивается определенное время. Для того, чтобы этот период прошел с максимальной пользой для клиента, создается отдельный экран с загрузчиком. Его основная задача – отображение текущего состояния ⏲ процесса загрузки. Подавайте анимацию интересно и оригинально. От этого также зависит, останется пользователь на сайте или покинет его.
Важно! Не стоит пренебрегать загрузчиком.
Правильно составленный Style Guide – это удобство использования для дизайнеров и разработчиков в процессе создания единого стилистического направления и верстки сайта. Несколько примеров готовых Style Guide которые мы разрабатывали:
В этом видео подробно рассказываем на пальцах что такое Style Guide и для чего он нужен:
Мы специализируемся на создании фирменного стиля, с учетом особенностей сайта и его специфики. Узнать подробную информацию об услуге создания Style Guide и оформить заказ, можно по указанным контактам или на странице данной услуги — узнать подробнее.
Вам понравился ❤️ материал? Поблагодарить легко! Будем весьма признательны, если поделитесь этой статьей в социальных сетях.
API Style Guide, или не заставляйте пользователей думать
Привет! Меня зовут Лёша Руцкой, и я — продуктовый менеджер в компании Wrike. До этого работал в Adform и PandaDoc. Последние пять лет я занимаюсь всем, что связано с интеграциями и API.
Wrike — это SaaS продукт для совместной работы и управления проектами. Мы хотим, чтобы разработчики строили свои решения на базе Wrike, а для этого нужно, чтобы наш API был удобным. При этом у нас 9 офисов по всему миру, и 3 из них — офисы разработки. Довольно сложно создавать консистентный API силами распределённых команд, которые говорят на разных языках. Растёт вероятность того, что их решения начнут противоречить друг другу. В этом случае не обойтись без единого для всех набора правил.
Если вы тоже работаете распределённо и делаете свой API, то API Style Guide может вам помочь. Я хочу рассказать, какие распространённые проблемы он решает и как облегчает жизнь разработчикам. Также поделюсь своим опытом по написанию и внедрению собственного API Style Guide в компании.
Зачем нужен удобный API?
Многим читателям наверняка приходилось решать проблемы с помощью не самого удобного API. Да, это не очень просто и занимает больше времени, но обычно всё-таки проблему решить можно.
Тогда зачем тратить время и усилия команды на то, чтобы сделать API лучше? Ответ достаточно прост: очень часто решение по поводу использования вашего продукта принимают разработчики, особенно если речь идёт об API и интеграциях. Поэтому важно задумываться не только про user experience (UX), но и про DX — developer experience.
Приведу пример. Когда-то я работал в команде, которая отвечала за все интеграции продукта. Часто в середине квартала, когда у нас уже были намечены планы, приходил маркетолог и говорил: «Компания Z сделала новый маркетплейс и релизит следующую версию своей платформы. Скоро у них будет крутое публичное мероприятие, на котором мы можем рассказать про нашу интеграцию и успехи! Будет здорово, если мы сейчас быстренько напишем эту интеграцию». Как мы поступали в таком случае? Если опытный разработчик в команде мог за три дня сделать минимальный работающий прототип, то чаще всего за две-три недели мы успевали довести задачу до идеального состояния. Если нескольких дней не хватало, значит API и документация были так себе. Перекраивать планы и браться за новую интеграцию для нас было бессмысленно — всё равно к установленному сроку ничего путного не получилось бы. Помните, что и ваш продукт может находиться в такой ситуации — партнёры будут решать, стоит ли иметь с вами дело в зависимости от того, насколько быстро и удобно можно начать работу с вашим API.
Но ведь вряд ли кто-то хочет спроектировать плохой API. Почему же у всех получается по-разному? Обычно API развивается так. Когда стартап начинает расти и к нему приходят первые клиенты, одна из команд делает свой endpoint и решает передавать версию в URL:
Постепенно появляются новые клиенты и новые потребности. В работу включаются ребята из второй команды, которые считают, что для версионирования лучше использовать собственные Media types:
Через некоторое время приходит третья команда. На одной из конференций они узнают, что Stripe версионирует свои API датами мажорных релизов. И решают сделать так же:
В итоге получается API, в котором есть три метода версионирования. Все методы работают, но работают по-разному.
Мне, как разработчику, было бы неудобно пользоваться таким API. И причина не в том, что я предпочитаю один подход к версионированию всем остальным. Просто использовать несколько способов одновременно — неудобно. Придётся три раза написать код, который работает с API, или использовать три разные библиотеки. А это значит, что и ошибок будет в три раза больше.
А ещё есть даты и время. Даже при использовании стандартного подхода данные можно передавать по-разному: по часовому поясу вашего сервера, по Гринвичу, по времени на клиенте, в Unix time. Клиентам надо будет приводить все данные к одному формату.
Сообщения об ошибках вообще все делают по-разному. Например, так:
Есть ещё моё любимое сообщение об ошибке — пустой ответ:
Ну и просто классика — ответ 200 OK, внутри которого лежит JSON c описанием, что же пошло не так.
На мой взгляд, самое главное в хорошем API — это консистентность. Неважно, какой именно подход к версионированию вы выберете, главное, чтобы он был одинаковый во всём API. Ещё более удачным решением будет взять популярный подход, которым уже пользуются другие компании. Скорее всего, ваши клиенты уже с ним сталкивались, и у них есть готовый код или библиотека. Не нужно лишний раз думать, можно использовать готовые инструменты.
Единый подход к созданию API особенно важен для больших компаний, в которых есть распределённые команды. Если десять человек в комнате создают стартап, то каждый разработчик может просто постучать соседа по плечу и договориться или увидеть основные проблемы во время code review. В большой компании это становится сложнее.
API Style Guide поможет вам решить такие проблемы. Это документ, который описывает принципы дизайна вашего API. Если все используют одни и те же подходы, то создаётся впечатление, что API разрабатывал один человек, а не множество разных команд. Этот подход во многом похож на Code Style Guide, когда команды договариваются о том, как они пишут код. Человек из одной команды может посмотреть кодовую базу другой команды и быстро понять, что там происходит.
Как сделать свой API Style Guide?
Arnauld Lauret (известен как API Handyman) создал классный сайт — API Stylebook. Он собрал публично доступные Style Guide, которые разные компании (Cisco, Google, Red Hat, государственные учреждения и многие другие) выложили в открытый доступ.
На сайте гайдлайны разбиты по темам. Например, если вас интересует версионирование, то на вкладке «Versioning» можно узнать, как разные компании решают эту проблему.
Учитесь на опыте других! Но полностью копировать чужой Style Guide — не самая хорошая идея. Всё-таки он решает проблемы другой компании, а не вашей.
В свой Style Guide вам стоит добавить темы, которые близки именно вашей компании и решают именно ваши проблемы. Может быть, у вас много мобильных приложений, и для вас важен размер ответа. Тогда опишите принципы, связанные с этим аспектом. Или вы договорились с внутренними командами о том, что пора распиливать монолит на микросервисы, которые будут общаться друг с другом через Message Broker. В этом случае в API Style Guide нужно включить принципы, по которым вы собираетесь использовать Kafka или какой-то другой инструмент.
Что ещё включить в API Style Guide
Также в Style Guide стоит включить базовые ценности и инженерные подходы, которых придерживается компания.
Какими они могут быть?
Вот как, например, это выглядит у Zalando:
О чём стоит помнить в начале работы над Style Guide
Как внедрить API Style Guide?
Вы сделали свой API Style Guide, и теперь осталось его внедрить. Это тоже бывает непросто. Я поделюсь своим опытом внедрения API Style Guide в одном из мест, где я работал. У компании была сложная структура: сотни инженеров, десятки распределённых команд в четырёх офисах разработки, коллеги говорили на разных языках.
Сначала нужно убедить стейкхолдеров. И тут речь часто идёт как о технических лидерах разных направлений, так и о представителях бизнеса. Все должны понимать, какие проблемы мы хотим решить и как Style Guide может в этом помочь. В моём примере все стейкхолдеры понимали, что хороший API — это важное преимущество. Многие клиенты приходили с таким запросом, да и конкуренты не дремали и активно расширяли объём возможностей, доступных через их API.
Следующая шаг — найти команду, которая это будет делать. В моём случае в компании уже была отдельная команда, которая поддерживала внешний API. Она лучше всех понимала необходимость изменений, потому что постоянно сталкивалась со сложностями в своей работе. Члены этой команды были рады поучаствовать в проекте.
Как команда внедряла API Style Guide?
Когда происходят ключевые изменения, часто появляются недовольные. В этом случае нужен авторитет, который сможет убедить этих людей в необходимости изменений. Техлиды — самые подходящие для этого люди.
API чемпионы в отдельном Slack-канале обсуждали возникающие вопросы и предложения. Мелкие изменения вносились сразу, а более крупные требовали подробного обсуждения. В этом случае инициатор писал официальное предложение: какую проблему нужно решить, какие способы решения уже существуют, какие у них есть преимущества и недостатки. Потом мы на 1-2 дня собирались на offsite за пределами офиса, обсуждали идеи, выбирали решение и фиксировали его. После рассказывали своим командам о принятом решении: почему мы приняли именно его и что нужно делать дальше.
Также API чемпионы помогали делать ревью по своим направлениям. Ребята в их командах сначала обращались к ним, а потом финальное ревью проводила команда, которая занималась созданием Style Guide.
Через какое-то время в компании начало формироваться API community. В него вошли люди, которые прошли несколько циклов ревью, разобрались в том, что такое хороший и правильный дизайн, зачем он нужен и как его сделать. Мы создали большой чат, в котором каждый мог задать вопрос, и члены API community помогали его решить.
Нельзя внедрить подход только на уровне инжиниринга. Команды sales, support и маркетинга тоже должны понимать, какие пользовательские сценарии покрываются API, какую ценность он несет, как соотносится со стратегией компании и как правильно донести информацию о нём до клиентов.
Мы постарались всё это внедрить в онбординг большинства команд в компании, в том числе — не инженерных. Это нужно ещё и для того, чтобы все понимали когда, в каких случаях и к кому можно приходить за помощью.
Автоматизация
Последняя важная тема — это автоматизация рутинных процессов. Ревью могут служить ярким примером. В большой компании с большим количеством команд, скорее всего, нужно будет делать очень много ревью. Не хочется тратить время на базовые проблемы вроде отсутствующего описания ошибки или неправильного формата ID.
В этом могут помочь некоторые инструменты:
Буду рад ответить на ваши вопросы о внедрении API Style Guide. Также будет круто, если вы поделитесь похожим опытом!
Отдельное огромное спасибо Дарье Ивановой за помощь в подготовке этой статьи!