Стайлгайд помогает оформлять статьи для вики так, чтобы они были понятными, структурированными и единообразными. Он пригодится техническим писателям, редакторам и всем, кто работает с документацией внутри компании.
Соблюдение стайлгайда так же обязательно, как и соблюдение норм русского языка.
Целевая аудитория вики-документации — пользователи ERP-системы с разным уровнем подготовки: от сотрудников склада до руководителей отделов.
Это могут быть новые пользователи, которым нужна пошаговая инструкция. Или опытные специалисты, которым важно быстро найти нужный раздел или параметр. Документация должна быть полезной, точной и понятной для всех.
❌ Не на Вы — это избыточно в инструкциях и создает ненужную официальность.
❌ И не на ты — потому что это неуместно в рабочей документации.
✅ Обращение на вы помогает сохранить нейтральный, уважительный и простой тон общения.
Например:
Нажмите Сохранить. Откройте меню Настройки. Запустите программу.
❌ юзер, логиниться, физлица, юрлица
✅ пользователь, войти в систему, частные клиенты, бизнес
Вместо этого пишите слова полностью. Если есть перечисление, используйте вводные вроде например и 2–3 варианта.
❌ Используйте фильтры для поиска по категориям, тегам и т.д.
✅ Используйте фильтры — например, по категориям, тегам или датам.
При первом упоминании напишите полное название, а сокращение — в скобках. В дальнейшем можно использовать только аббревиатуру.
Например: система управления базами данных (СУБД).
❌ Вам нужно нажать Сохранить.
✅ Нажмите Сохранить.
Используйте модальные глаголы только в тех случаях, когда они действительно важны для понимания действия.
Например:
Вы можете выбрать любой из предложенных вариантов.
Каждый заголовок должен четко отражать содержание раздела.
Используйте только заголовки второго и третьего уровней (##, ###)
Заголовок первого уровня (#) — это название самого раздела или страницы (например, База знаний). Оно задается системой автоматически или вручную один раз. Для самой статьи достаточно ## и ###, чтобы не перегружать структуру и не сбивать оглавление.
Заголовки четвертого уровня (####) не используем — они делают текст тяжелым для восприятия. Если информации слишком много — лучше вынести ее в отдельную статью.
После # идет ##, затем ### — не пропускайте уровни.
Не перегружайте текст под заголовками: старайтесь разбивать на подразделы, если много информации.
Заголовки не должны быть длиннее 7 слов (без предлогов и союзов).
Пишите инструкции по схеме. Такой подход помогает пользователю быстро понять, что от него требуется, и успешно выполнить действия с первого раза.
Используйте встроенные макросы выделения, чтобы привлечь внимание к важному. Они помогают быстро заметить важные детали и не перегружают текст. Используйте макросы по смыслу:
ℹ️ Информация
Обновления сохраняются автоматически каждую минуту.
⚠️ Предупреждение
Удаленные документы невозможно восстановить.
💡 Совет
Чтобы ускорить работу, используйте горячие клавиши.
Важно: в печатной документации скриншоты подписываем и оформляем как полагается. Смотрите редполитику.
Примеры кратких пунктов:
Примеры пунктов с несколькими предложениями:
Жирный — для названий кнопок, полей и меню в вебе
Курсив — для акцентов и пояснений
Жирный курсив — для путей, идентификаторов, параметров конфигураций
Пример:
Откройте файл C:\Windows\notepad.exe.
Тире — это не дефис.
Тире (—) используется в предложениях для смысловых акцентов или логического противопоставления: Пример: Он занимается складом, а я — отгрузками.
Дефис (-) соединяет части слова. Пример: клиент-сервер, что-нибудь, кто-то.
Среднее тире (–) ставится между числами: Пример: 10–15 товаров.
В вики используйте только длинное тире (—) и среднее тире (–), в зависимости от контекста. Не заменяйте их дефисом.
В вебе и вики не используем кавычки вообще. Это утяжеляет верстку и мешает восприятию. Правило не относится к печатной документации.
Если в статье есть длинный список — от 10 пунктов, используйте макрос [details], чтобы список можно было развернуть по клику. Это экономит место и не перегружает страницу.
Пример
Сама разметка выглядит так
<details>
<summary>Список возможных статусов</summary>
- В ожидании
- Принят
- В пути
- Доставлен
- Отменен
</details>
Теги позволяют быстрее находить статьи через поиск и связывать материалы между собой.
Чтобы упростить навигацию и не повторять одно и то же в разных статьях, используйте перекрестные ссылки. Они помогают перейти к нужному разделу сразу, не теряя контекста.
Когда использовать ссылки:
Формат ссылки:
Если ссылка внутренняя:
< [Подробнее в статье Возврат товара] (../vozvrat-tovara)
Если внешняя:
<[официальный сайт] (https://...)
Между квадратными и круглыми скобками нет пробела.