Дисклеймер: это продолжение темы о составлении правильной технической документации. В первой статье мы рассказали, какие цели преследуются при составлении инфраструктурной документации и какие у нее особенности. А теперь поговорим о том, как составить годный стайлгайд, чтобы документы были удобочитаемыми, консистентными и… может быть, даже красивыми :-)
Что такое стайлгайд?
Дословный перевод английского словосочетания Style guide — «руководство по стилю». Применительно к документации это набор правил и требований, включающий особенности стиля и тона изложения, оформления текста и структуры, использования терминологии и т.д.
Стайлгайд обеспечивает консистентность текста, ускоряет адаптацию новых сотрудников и экономит время, сводя к минимуму дискуссии о том, как правильно писать или оформлять текст.
В англоязычном сегменте интернета легко найти стайлгайды разных компаний: например, Google, Mailchimp, Veeam. Они буквально-таки всеобъемлющие. Но годятся только для английского языка. А как быть с русским?
Как таковых «стайлгайдов» для великого и могучего нет. Но есть ГОСТы, из которых можно почерпнуть информацию о структуре и содержании тех или иных технических документов; есть “Справочник издателя и автора”, который дает наиболее полную информацию о правилах оформления документов; наконец, есть справочник Д. Э. Розенталя с правилами правописания.
Все они являются фундаментальными источниками, однако было бы слишком трудозатратно каждый раз лазить в них и искать очередной ответ на вопрос «как правильно?» Так что проще один раз сильно напрячься и составить свой стайлгайд, который будет опираться на эти источники и содержать наши локальные правила.
Стайлгайд: начало
Мы разделили стайлгайд на три основных части. Или на три документа:
- стайлгайд документации в вики-системе;
- стайлгайд составления схем;
- стайлгайд документации для клиентов.
Различия правил документации в вики-системе и документации, которая передаётся клиентам, обусловлены по большей части, используемым инструментарием. У нас вики-система Confluence, и у клиентов нет к ней доступа. Им мы передаем документацию в формате офисных документов или переносим в их базу знаний. По этой причине и существуют определенные различия в структуре и оформлении документов.
Вначале мы выделили основные вопросы, которые возникают у технического писателя при создании документации:
— Как мы пишем те или иные термины? Например, мы пишем «кубернетес» или «Kubernetes»? Или «k8s»?
Ответ на такой вопрос должен давать глоссарий. И значит он нам нужен.
— В каком порядке располагаем статьи и как заполняем шаблоны? Какой структуры придерживаемся?
Нужны правила структуры по пространствам, разделам, подразделам и статьям.
— Как мы пишем? Подробно или кратко? Какой стиль написания используем?
Нужно сформулировать хотя бы несколько основных правил.
— А каким языком? Например, насколько допустимо использование профессионализмов, сокращений, канцеляризмов и т.п?
Нужны конкретные правила их использования в документации. А также любые другие правила по написанию, которые помогут привести документацию к единому виду.
— Как мы оформляем документацию? Какие используем шрифты, цвета? Как оформляем списки и заголовки? Какие элементы и макросы используем и для чего? Какие правила использования жирного и курсива, кавычек, таблиц, изображений, видео и т.д.
Нужны правила оформления.
— Как привести схемы к единому виду? Какие есть общие правила при их составлении? Что нужно отобразить на схеме, какие отношения и связи? Какие типы схем мы составляем?
Нужно сделать унификацию элементов схемы, записать правила использования цветов, шрифтов и размеров, составить библиотеки используемых элементов и привести примеры правильных схем, в которых наиболее полно используются элементы и показаны связи между ними.
В глоссарий мы записали самые распространенные термины, с которыми возникала путаница, и оформили его в виде таблицы:
Её предполагается заполнять и дальше — каждый может добавить термин, которому нужно дать понятное определение и правильное обозначение в документации.
Основной стайлгайд включает в себя следующие разделы:
Во введении мы дали небольшое определение для стайлгайда и указали, для каких пространств мы применяем его правила.
Целевая аудитория — это краткий портрет пользователей, для которых пишется документация. Он позволяет правильно сформулировать правила написания и язык статей.
Раздел с оформлением статей включает в себя такие правила, как:
- обязательное использование макроса оглавления;
- использование заголовков: определили, что для структуры наших статей будет достаточно заголовков 2-го и 3-го уровней — использование заголовков ниже третьего уровня будет только усложнять структуру;
- использование для кода и файлов конфигурации макроса — «блок кода»;
- использование макросов выделения. Например, в каких случаях использовать макрос «информация», а в каких «предупреждение»;
- использование макроса «раскрыть» для длинных списков. Особенность нашей документации в том, что там часто используются списки и они могут существенно удлинять статью. Поэтому если в списке более 10 пунктов, то такой список желательно сделать раскрывающимся;
- использование макроса drawio для схем. Так как схемы требуется постоянно обновлять, то удобнее, когда в документации они располагаются не в виде картинки, а внутри макроса. Это позволяет быстро и просто вносить в схему нужные изменения;
- использование дефисов и тире, жирного и курсива;
- подписи к картинкам и скриншотам — в каких случаях они нужны, а когда их можно опускать;
- использование маркированных и нумерованных списков — в чем разница, когда и какой нужно использовать. Также правила их оформления — пункты маркированных списков начинаются с маленькой буквы и заканчиваются точкой с запятой, пункты нумерованных списков начинаются с заглавной буквы и заканчиваются точкой;
- использование макросов для добавления ссылок и таблиц.
В описание структуры разделов и статей мы включили сначала общие правила структурирования: нужно ли располагать информацию в родительских статьях, когда статьи нужно объединять в один подраздел, как менять порядок страниц.
Далее мы определили частные правила для некоторых пространств в Confluence. Например, для большого раздела, в котором находится документация по клиентским проектам: так как это основной раздел, с которым работают тех.писатели, то правила его структуры мы описали наиболее подробно.
Например, мы определили четыре основных возможных варианта структуры клиентского проекта:
- простой;
- стандартный;
- расширенный 1;
- расширенный 2.
Для наглядного представления структуры была составлена майндмапа, в которой расписан каждый из 4-х вариантов структуры:
На примере стандартного варианта (самого распространенного) описали предназначение каждой статьи. Также добавили указание на использование шаблонов для статей, если таковые наличествуют, и инструкцию по их заполнению.
В разделе Расстановка тегов — правила, по которым нужно добавлять теги: обязательные теги, типы тегов для инструкций, теги при наличии алертов и т.д.
При этом правила тегов для пространства с документацией по клиентским проектам и остальными разделами несколько различаются. Эти различия также добавлены в стайлгайд.
В последнем разделе основного стайлгайда — язык статей. Мы указали все основные правила, которых нужно придерживаться при написании статей документации:
- длинные предложения лучше разбивать на короткие;
- названия статей желательно делать короткими и лаконичными;
- избегаем слов и предложений без конкретной смысловой нагрузки;
- статьи пишем не сплошным текстом, а разбиваем на разделы и подразделы;
- инструкции пишем в повелительном наклонении — «сделайте», «добавьте» и т.д.;
- термины указываем согласно глоссарию;
- стараемся не использовать: канцеляризмы, профессионализмы и жаргонизмы, сложные и длинные предложения с причастиями и деепричастиями, пассивный залог, вводные конструкции («на мой взгляд», «кстати» и т.п.), оценки и усилители («эффективный», «идеальный» и т.п.), а также слова, создающие неопределенность, повторы и тавтологию в тексте.
Правила оформления схем мы вынесли в отдельный стайлгайд:
Введение описывает, какие типы схем мы составляем и для чего применяется этот стайлгайд.
В общих правилах оформления мы указали:
- какие использовать шрифты, размеры текста, цвета самого текста и его фона. При этом отдельно расписали их для элементов сервера, текста указателей и текста доп.описаний;
- оформление блоков элементов — какие использовать фигуры и палитру цветов, нужно ли использовать скругление и градиент, насыщенность элементов заднего плана;
- правила загрузки сторонних и больших изображений;
- единый размер элементов сервисов;
- варианты группировки серверов, подсетей;
- варианты изображения подключений и репликаций;
- варианты группировки элементов и сервисов.
В правилах оформления элементов облачных сервисов описано:
- использование иконок, соответствующих сервису, из готовых библиотек облаков;
- сохранение пропорций и стандартных цветов иконок.
Также мы добавили примеры для схем облачных сервисов.
В остальном стайлгайд схем находится в стадии активной разработки. Планируется добавить больше примеров разных типов схем, внести их описание и предназначение, а также составить собственную библиотеку готовых элементов, которые мы часто используем.
Правила оформления для документации, которая передается клиентам, мы также оформили в отдельный документ со следующим содержанием:
Разделы Введение и Язык написания полностью дублируют основной стайлгайд — здесь правила едины как для статей в вики-системе, так и для офисных документов. Эти разделы скопированы сюда только для удобства — чтобы все правила для определенных документов были в одном месте.
В одноименном разделе мы определили основные типы документов, которые мы передаем нашим клиентам на текущий момент:
- приёмо-сдаточная документация;
- отчет по нагрузочному тестированию;
- отчет по аудиту Kubernetes.
В разделе оформление документов мы подробно описали следующие правила:
- какие мы используем шрифты;
- размеры основного текста и заголовков;
- используемую цветовую гамму;
- размеры полей, используемое выравнивание;
- отступы и междустрочные интервалы;
- использование нумерации, рисунков и подписей к ним;
- использование таблиц и подписей к ним;
- обязательное содержание документов — титульный лист, оглавление, основная часть, заключение;
- использование дефисов и тире;
- использование маркированных и нумерованных списков;
- использование логотипа ITSumma.
На этом основной этап создания стайлгайда завершен. Главных доработок требует только стайлгайд для схем.
Какие проблемы решило наличие стайлгайда
Попробую теперь сформулировать, какие именно проблемы мы решили при помощи стайлгайда:
- Приведение документации к единому виду. Это помогает быстрее и проще ориентироваться по документации.
- Сокращение времени на адаптацию нового сотрудника в отделе документирования. Теперь не нужно передавать знания из уст в уста, всё хранится в одном месте.
- Сокращение времени на подготовку документов для клиентов. То есть ускорение оказания услуг нашим заказчикам.
- Формализация знаний, которые ранее хранились в головах разных людей.
Плюс во время составления стайлгайда родились и другие идеи по улучшению и упрощению работы тех.писателей. Мы поняли, каких инструкций нам не хватает, и некоторые даже написали, структурировали свои знания и организовали собственную базу знаний. Это улучшило взаимодействие между тех.писателями.
Какие вопросы остаются
Самый основной вопрос и сложность — как привести всю документацию в соответствие со стайлгайдом и как это соответствие поддерживать…
Приводить документацию к новому виду мы начали с раздела клиентской документации. Но и это делается не по принципу «ну-ка навались», а постепенно, так как процесс этот довольно трудозатратный. Постоянно нужно вносить правки, добавлять документацию к новым проектам, править схемы и т.д. Поэтому приведение документации к новому виду разбивается на подзадачи по проектам и выполняется как второстепенная задача.
Но даже если бы было возможно разом привести документацию к красивому и правильному виду, то остается вопрос, как ее поддерживать в таком виде.
Пока самым логичным решением видится добавление обязательного этапа ревью. Он будет включать не проверку технических вопросов и смыслового содержания статей, а соответствие букве закона стайлгайдам. Ревью можно сделать перекрестным — это, во-первых, улучшит качество статей и повысит соответствие принятым правилам, а во-вторых, доведёт следование правилам до автоматизма на эти правила — все выучат их назубок и будут быстро находить и исправлять несоответствия.
Что дальше?
Стайлгайд наш не отлит в граните: он может и должен изменяться, дополняться и улучшаться. Поэтому было бы здорово через некоторое время вновь осмыслить глобально, что из введенных правил актуально, а чем так и не стали пользоваться. Например, потому что всем проще и привычнее делать вот так, а не так как написано.
Если эта статья станет для вас импульсом к созданию собственного стайлгайда (на что я надеюсь :-) ), пишите в комментариях вопросы — на все отвечу, чем смогу — помогу.