Что такое руководство по стилю?

Руководство по стилю, или «стайл гайд» (style guide), — это сборник правил, которым следуют все технические писатели в рамках одной компании или проекта.

Зачем нужно руководство по стилю?

Хорошая документация выглядит так, словно её всю написал один человек. Иногда так и есть, но чаще созданием документации занимаются команды.

У каждого технического писателя может быть свой стиль, уровень квалификации, привычки, профессиональный опыт и так далее. Руководство по стилю устраняет это неравенство. Когда все техписы создают текст, выдержанный в одном стиле — это хорошо.

Что входит в руководство по стилю?

В каждой компании по-разному, но есть и общие части.

Типы документов

Документы бывают разные:

• Инструкция администратора.

  Администраторы будут нашу систему обслуживать. Они должны хорошо знать как система устроена изнутри, какие есть ограничения, как делать резервное копирование и восстановление, и так далее.

• Инструкция пользователя.

  Пользователь не хочет знать в какой конфигурации у нас развёрнут кластер Greenplum, ему всё равно. Его уровень — внесение данных в базу, формирование отчётов, настройка шаблонов для экспорта в PDF и так далее.

• ПМИ, они же Программы и Методики Испытаний.

  Этот документ создаётся для комиссии, которая выполняет приёмку продукта. Задача ПМИ — описать способы проверки функциональности вашего продукта. Допустим, ваш продукт умеет делать А. Джентльмены верят друг другу на слово, но тут другая ситуация. Расскажите, как убедиться, что функция А действительно работает. Что насчёт Б? Как понять что В работает так, как написано в описании продукта?

• FAQ

  Сборник вопросов и ответов на них. Хороший FAQ формируется на основе вопросов, заданных в техническую поддержку. Иногда FAQ вырастает в базу знаний.

Способ обращения к читателю.

Обычно здесь фиксируют форму глаголов:

Нажмите кнопку.

Нажми кнопку.

Необходимо нажать кнопку.

Используя этот переключатель, вы можете…

Запреты

Я бы запретил писать такое:

• Всё, что запрещено действующим законодательством.

• Шутки, отсылки и эвфемизмы.

  • Вы пишете техническую документацию. Хотите писать анекдоты или тексты для стендапов — смените место работы.

  • Шутка может показаться хорошей вам и оскорбительной — другому человеку.

  • Шутка может быть непонятной или несмешной.

  • Шутки со временем устаревают. То, что смешно сейчас, через несколько лет выглядит жалко. Кроме анекдота про нюанс, конечно же. Это классика, блядь! Это знать надо!

• Личное отношение к материалу.

  Низкое качество продукта? Нелогичность размещения разделов? Странное поведение отдельных разделов? Опечатки в UI? Придержите своё мнение при себе, хорошо? Текст не должен ничего говорить о вашем психологическом и моральном состоянии.

• Жаргонизмы.

  Инсталлируйте пэкедж для корректной обработки роутов, ёпта!

Описание элементов UI

Это если у вас вообще есть UI. Бывают продукты без него.

• Нажимаем кнопку или на кнопку?

• Как называем чекбоксы?

  • Галочки?

  • Флажки?

  • Флаги?

• Что насчёт форм? Называем их как-то или нет?

• Если поле имеет особенности, пишем про них простым текстом или с помощью Admonition? Прячем под спойлер или нет? Спойлер по умолчанию раскрыт или свёрнут?

• Делаем скриншоты или нет?

• Если делаем, то в каком разрешении?

• Что насчёт данных? Используем размытие, чтобы скрыть информацию, или пренебречь, вальсируем?

Переводы

В руководство по стилю можно добавить переводы для разных терминов. Очень плохо, когда в одном месте вы создаёте каталог, в другом — папку, а в третьем — директорию.

Всё должно быть как в армии — безобразно, но однообразно.

Также можно составить

Заключение

Руководство по стилю — один из важнейших руководящих документов для технического писателя. Важнее только трудовой договор.

Не пренебрегайте руководством по стилю. Регулярно обновляйте его и фиксируйте в нём договорённости с командой. Если один раз решили, что будете какие-то вещи описывать в таком-то ключе — не держите в голове, запишите, и сможете потом на ревью ссылаться на нужный пункт. И команде легче, и вам.