Styleguide

This document explains how to create, format, and maintain documentation in the knowledge base.

В качестве ориентиров используйте страницы How to Create and Send an Envelope, Personal Settings Page Overview, How to Edit Personal Account Settings и What Is an Envelope Chain?.

Что уже является стандартом

• короткий и конкретный description

• понятный заголовок с предсказуемым паттерном

• Heading 2 для основных смысловых блоков

• нумерованные шаги для инструкций

• короткие списки и колонки для обзоров

• hint-блоки для ограничений, нюансов и предупреждений

• скриншоты рядом с действием или элементом интерфейса

• ссылки на связанные страницы вместо дублирования текста

Не создавайте дубли

Один процесс должен жить на одной странице.

Если тема уже описана:

• Обновите основную страницу.

• Добавьте ссылку на неё из смежной статьи.

• Вынесите повторяющийся блок в reusable content, если он нужен в нескольких местах.

Не создавайте новую страницу только потому, что в другом разделе этот же сценарий встречается в другом контексте.

Тип документа

Перед написанием определите тип материала.

Инструкция (Instruction/Guide)

Используйте этот формат, если пользователь должен выполнить действие.

Паттерн заголовка:

• How to + действие

Примеры:

• How to Create and Send an Envelope

• How to Edit Personal Account Settings

Обзор (Overview)

Используйте этот формат, если нужно показать состав страницы, раздела или набора функций.

Паттерн заголовка:

• сущность + Overview

Примеры:

• Personal Settings Page Overview

• Integrations Page Overview

База знаний (What is/Reference)

Используйте этот формат, если нужно объяснить функционал.

Паттерн заголовка:

• What Is + сущность

• название сущности без лишней детализации

Примеры:

• What Is an Envelope Chain?

• Access Levels

API-материал (API article)

Добавляйте пометку API, если сценарий относится только к API.

Примеры:

• Create a Callback (API)

• Envelope Metadata (API)

Как называть страницы

Заголовок должен быть коротким и поисковым. Старайтесь создавайте его с расчётом на то, чтоб юзеру было удобно его загуглить.

Делайте так:

• Сохраняйте паттерны How to, Overview, What Is.

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

Не делайте так:

• Не добавляйте в заголовок лишний контекст.

• Не смешивайте в одном заголовке несколько названий функционала.

Description

У каждой страницы должен быть короткий description.

Используйте один из двух паттернов:

• This document explains ... — для инструкций, гайдов и объясняющих материалов

• This document contains ... — для обзоров, списков, каталогов и справочных подборок

Description должен:

• отвечать на вопрос, что именно получит читатель

• помещаться в 1–3 коротких предложениях

• желательно не повторять заголовок слово в слово

Хорошо:

• This document explains how to use QuickSend in the DocStudio Dashboard to upload external files and send them for signing by configuring recipients and roles.

• This document describes where to find Recently Used Templates on the dashboard and how to use it.

Плохо:

• This page contains useful information.

• This document explains everything about envelopes.

Рекомендуемая структура страницы

Для инструкций по продуктовому сценарию используйте структуру, которая хорошо видна в How to Upload a Document for e-Signature.

Собирайте страницу в таком порядке:

1. Добавьте title и description.

2. Начните страницу с основного сценария, ради которого пользователь открыл материал.

3. Поставьте крупный скриншот или GIF перед основной инструкцией, если он помогает быстро понять экран.

4. Сразу после медиа добавьте hint с главным ограничением, если оно критично для сценария.

5. Дайте пошаговую инструкцию в нумерованном списке.

6. После основной инструкции добавьте обзор ключевого экрана, модального окна или блока настроек.

7. Расшифруйте элементы интерфейса нумерованным списком, если на скриншоте есть несколько важных зон.

8. Вынесите отдельные правила, ограничения и supported values в hint-блоки или короткие списки.

9. После основного сценария добавьте связанные подзадачи в отдельных блоках Heading 2.

10. Для связанных подзадач используйте тот же паттерн: медиа, короткое объяснение, шаги, ограничения.

11. Завершите страницу дополнительными правилами, mapping, edge cases или related actions, если без них сценарий будет неполным.

Рекомендуемый каркас для такой инструкции:

1. Main action

2. Modal / screen overview

3. Rules or saved behavior

4. Related action 1

5. Related action 2

6. Conversion, mapping, restrictions, or edge cases

Если блок можно понять без вводного текста, переходите сразу к шагам или списку опций. Не пишите вступление ради вступления.

Заголовки

Используйте Heading 2 для основных разделов страницы. Используйте Heading 3 для подразделов внутри одного сценария.

Не делайте заголовки декоративными. Каждый заголовок должен отвечать на вопрос, что читатель найдёт в блоке.

Хорошо:

• Create a template

• Connection details

• Finalise the template

Плохо:

• Important information

• Useful notes

• Misc

Текст и тон

Все инструкции пишите в imperative form.

Сохраняйте стиль, который уже используется в базе:

• короткие предложения

• одно действие на один шаг

• минимум вводных фраз

• максимум конкретики

Пишите так:

1. Open the admin panel.

2. Go to Account icon settings or Platform logo settings.

3. Click Set default.

Названия интерфейса и терминология

Названия программ, кнопок, полей и разделов выделяйте жирным и пишите без кавычек.

Если это возможно, показывайте кнопку не только текстом, а через inline screenshot самой кнопки. Так пользователю проще распознать элемент по цвету, форме и расположению.

Примеры описания кнопок:

1. Click the button and select an image.

2. Click the button.

3. After any edit, click the button.

Используйте названия в том виде, в котором их видит пользователь.

Пишите единообразно:

• Dashboard

• Mailbox

• Templates

• Admin panel

• Notifications

• Send

• Save draft

• Add recepient

Если DocStudio использует один термин, не подменяйте его синонимами в соседних статьях. Например, если в интерфейсе используется Mailbox, не чередуйте его с folder, inbox или department.

Списки

При оформлении маркированных списков:

• Пункты, которые выражены одним словом или словосочетанием, пишите с маленькой буквы и не ставьте точку.

• Если пункт является полноценным предложением, пишите его с большой буквы и ставьте точку.

Если список очень длинный, размещайте пункты в 2–3 колонки. Так страница выглядит компактнее.

Используйте этот паттерн, когда список не является пошаговой инструкцией и хорошо читается в компактной раскладке.

Пример короткого списка

• capture button

• area selector

• blur tool

• autosave

Пример списка из предложений

• Start each article with a short description.

• Use headings of different levels to build a clear structure.

• Check all links before publishing.

Recommendations for documentation

• Start each new article with a short description of its purpose.

• Use headings of different levels to build a clear structure.

• Check all links before publishing the page.

• If the list is too long, place the items in 2–3 columns to keep the page compact.

Для пошаговых инструкций используйте нумерованный список.

В таких списках:

• one step = one action

• each step starts with a verb

• use a capital letter and a period if the step is a full sentence

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

Такой формат подходит для пошаговых инструкций.

Example of a numbered instruction:

1. Open the admin panel.

2. Go to Account icon settings or Platform logo settings.

3. Click the button and select an image.

4. Click the button.

Ссылки

Ссылки зашивайте в текст.

Правильно:

• Check the text with LanguageTool.

Неправильно:

• Check the text with https://languagetool.org/ru.

Когда тема уже раскрыта в другой статье:

• Дайте ссылку на основную страницу.

• Не копируйте в новую страницу целые блоки текста.

Проверяйте орфографию и грамматику с помощью LanguageTool.

Скриншоты и GIF

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

Для простоты восприятия информации читателем, описания функционала на скришоте стоит оформлять в 2 колонки с помощью макроса columns.

• в левой колонке — описание функционала

• в правой колонке — скриншот этого функционала

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

Используйте такие правила:

• Ставьте скриншот сразу после шага или блока, к которому он относится.

• Показывайте только нужную область интерфейса.

• Убирайте лишний визуальный шум.

• Не оставляйте на изображении чувствительные данные.

• Обновляйте скриншоты после изменений UI.

GIF используйте для сценариев, которые сложно объяснить статикой и будет проще понять, если есть визуальный видеоряд, например как создать таблицу или добавить нового юзера и тд..

Если действие очевидно из текста, не добавляйте изображение ради количества.

Паттерны раскладки: текст и скриншоты

Two columns: bullet list + screenshot

Используйте этот вариант, когда нужно кратко описать набор полей, опций или свойств без пошаговой инструкции.

1. В левой колонке размещайте — маркированный список функционала на скришоте с его описанием и названием полей.

2. В правой колонке — сам скришот функционала.

Примеры в текущей документации:

• Text Field

• Number Field

• Currency Field

Two columns: numbered list + screenshot

Используйте этот вариант, когда слева нужно показать короткую последовательность действий, а справа — соответствующий экран.

1. В левой колонке размещайте — пронумерованную инструкцию/пронумерованное на скришоте описание полей/функционала.

2. В правой колонке — сам скришот функционала.

Примеры в текущей документации:

• Раздел Set the template access level in How to Create and Configure a Template.

• Раздел Finalise the template in How to Create and Configure a Template.

Full-width screenshot above the instruction

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

Сначала ставьте крупноразмерный скриншот

Потом размещайте саму инструкцию или описание функционала.

Примеры в текущей документации:

• Раздел Edit the account name in How to Edit Personal Account Settings

• Раздел Create a mailbox in How to Create a Mailbox

GIF before the instruction

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

1. Над инструкцией ставьте GIF анимацию.

2. Размещайте пошаговую инструкцию с описанием функционала показанного в анимации.

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

Примеры в текущей документации:

• How to Add or Edit an e-ink signature

• How to Add or Edit Initials

Hint-блоки и другие блоки оформления

_Hint

_{Используйте:}

• _{info — для пояснения, ограничения или дополнительного контекста}

• _{warning — для риска, условия или важного ограничения}

• _{danger — для необратимого действия}

• _{success — для подтверждения результата, если это действительно нужно}

_{Hint должен быть коротким. Не превращайте его в отдельную главу.}

_Columns

_{Используйте колонки, если нужно компактно показать:}

• _{короткие списки}

• _{текст рядом со скриншотом}

• _{две равноправные группы настроек}

_{Не помещайте в колонки длинные абзацы.}

_{Таблицы}

_{Используйте таблицу, если нужно сравнить или перечислить однотипные сущности.}

_{Подходящие случаи:}

• _{параметры и их значения}

• _{статусы и их смысл}

• _{права доступа}

• _{состав отчёта}

• _{различия между режимами}

Версионность и поддержка актуальности

Ведите страницу как один актуальный источник правды.

Если функциональность изменилась:

• Обновите существующую страницу.

• Удалите устаревшие шаги.

• Замените старые скриншоты.

• Проверьте, не сломались ли ссылки на эту страницу из других разделов.

Не заводите отдельные страницы формата v2, new, updated или draft без реальной необходимости.

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

Чеклист перед публикацией

Перед публикацией проверьте страницу по этому списку:

• Тип страницы выбран правильно.

• Заголовок легко ищется.

• Description короткий, конкретный и начинается с This document explains или This document contains.

• Страница начинается с основного сценария, а не со второстепенных деталей.

• Основная структура страницы выстроена логично: основной сценарий, обзор экрана, правила, связанные действия, ограничения.

• Все инструкции написаны в imperative form.

• Маркированные списки оформлены по правилу: фразы — с маленькой буквы без точки, предложения — с большой буквы с точкой.

• Нумерованные списки оформлены по правилу: каждый полноценный шаг начинается с большой буквы и заканчивается точкой.

• Длинные списки разложены в 2–3 колонки, если так страница читается лучше.

• Названия кнопок, полей и разделов выделены жирным и написаны без кавычек.

• Кнопки показаны через inline screenshot там, где это помогает быстрее узнать элемент.

• Для скриншотов выбран правильный паттерн: 2 колонки, full-width screenshot над информацией или GIF перед.

• Скриншоты и GIF актуальны и помогают понять действие.

• Ограничения, важные условия и исключения вынесены в hint-блоки.

• Нет дублирования с уже существующими страницами.

• Все ссылки зашиты в текст, работают и ведут на актуальные материалы.

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