Руководство по стилю — это правила, которым следует все технические писатели, работающие над одним проектом.

Цели

Цели, ради которых создаётся руководство по стилю:

  • Фиксация правил написания документов разных типов.

    Хорошее руководство по стилю должно содержать правила, описывающее в общих чертах структуру и содержимое каждого типа документа, который есть на проекте.

  • Фиксация переводов.

    Если документация использует переводы терминов, руководство по стилю должно фиксировать как именно переводить тот или иной термин. Плохо, когда в одном предложении directory перевели как «директория», в другом как «папка», а в третьем — «каталог».

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

    Руководство по стилю задаёт правила обращения к читателю. На «вы», «Вы» или обезличенно.

  • Правила описания UI.

    Если у приложения есть UI, здесь рассказывается какие элементы интерфейса он содержит, как они называются в документации и как про них писать.

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

Обычно выделяют эти:

  • Описание API.
  • Концепция.
  • Инструкция.
  • Практическое руководство.

Описание API

Как правило, описание API делают с помощью одного из широко распространённых фреймворков типа Swagger. В этом случае описание API формируется автоматически на этапе сборки проекта. Способ формирования описания не так важен. Важно то, что описание даёт читателю:

  • Описание правил доступа к API.
  • Список конечных точек (эндпоинтов).
  • Правила заполнения данных при создании запросов.
  • Описание ответов.

Концепция

Концепция содержит описание того, как работает вся система или отдельная её часть.

Примеры концепций:

  • Общее устройство системы или приложения.
  • Детальное описание внутреннего устройства отдельных компонентов.
  • Управление доступом.
  • Взаимосвязи между разными частями системы.

Чего концепция содержать не должна, так это описания действий, которые должен выполнить пользователь.

Инструкция

Инструкция описывает работу с частями системы, не важно, через API или графический интерфейс. Хорошая инструкция, как правило, состоит из таких пунктов:

  • Переход к списку объектов.
  • Просмотр детальной информации об отдельном объекте.

  • Создание новых объектов.

    В этом случае часто описываются правила заполнения полей, например, список разрешённых символов, ограничение по длине, влияние одной настройки на другие и так далее.

  • Изменение свойств существующих объектов.
  • Удаление объектов.

В инструкциях допускается приводить примеры, но они должны помогать читателю, а не запутывать его. Плохо, когда после чтения инструкции у читателя количество новых вопросов перевешивает количество полученных ответов.

Практическое руководство

Практическое руководство, в отличие от инструкции, содержит практический пример использования системы. Типовое практическое руководство состоит из таких разделов:

  • Общее описание.

    Этот раздел отвечает на вопрос: «Что я получу, если выполню инструкции из этого руководства?». Тем самым мы экономим время читателя: ему достаточно прочитать один или два абзаца, чтобы понять, нужно ли читать дальше.

  • Системные требования.

    Если для выполнения руководства нужно подготовить стенд, то требования к нему указываются в этом разделе.

  • Перед началом работы.

    Здесь описываются подготовительные мероприятия: настройка доступов, размещение ключей SSH, создание учётных записей и так далее. Другими словами, типовые действия по настройке стенда. Часто этот раздел объединяют с предыдущим.

  • Шаги практического руководства.

    Здесь описываются шаги, имеющие прямое отношение к задаче, описанной в самом начале.

  • Проверка корректности.

    Необязательный раздел, позволяющий убедиться, что всё сделано правильно. Чаще шаги проверки добавляют прямо в практическое руководство по принципу «Fail fast», то есть «Чем раньше мы узнаем что что-то пошло не так, тем лучше».

Отличия практического руководства от инструкции

Инструкция, как правило, описывает работу с отдельным разделом системы. Практическое руководство может захватывать несколько разделов системы, но без детального описания. Например, в практическом руководстве не место правилам заполнения полей. Предполагается, что читатель уже знаком с ними. Также часто в практических руководствах делают ссылки на инструкции. Но не наоборот!

Практическое руководство может использовать примеры заполнения полей. Инструкция обычно ограничивается абстрактными примерами.

Практическое руководство описывает частный случай использования системы, в то время как инструкция даёт описание всех возможных полей и нюансов.

Переводы

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

В этом примере для каждого термина приводится несколько синонимов. Первым в списке идёт тот перевод, который следует использовать. Для большей наглядности он выделен жирным.

Оригинал Перевод
browser браузер
  веб-браузер
  интернет-браузер
  интернет-обозреватель
directory директория
  каталог
  папка
playbook плейбук
  сценарий
script скрипт
  сценарий
shell оболочка
  шелл

Должны ли переводы удовлетворять правилам русского языка?

При всём уважении к Дитмару Эльяшевичу Розенталю, он не был носителем языка, и свои правила писал механистически. Таким образом, «имя файла» уже прижилось и звучит более естественно, чем «название файла». Кстати, если города и улицы носят названия, то почему их переименовывают, а не переназывают?

Правила описания UI

Этот раздел руководства по стилю отвечает на эти вопросы:

  • Какие элементы UI есть в системе?
  • Как они называются?
  • Как правильно, «нажмите кнопку» или «нажмите на кнопку»?
  • А ссылки? «Нажмите ссылку» или «нажмите на ссылку»?
  • Как оформлять названия полей, а как — примеры вводимых значений?
  • А если значение выбирается из списка, то его оформляем жирным или курсивом?
  • А если значения в списке не фиксированные, а задаются пользователем на более ранних этапах?

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