Документация Discourse в настоящее время пересматривается и редактируется для соответствия этому руководству по стилю. Не все темы документации в данный момент полностью соответствуют этому — мы работаем над этим как можно быстрее.
Это считается живым документом, который определяет, как пишется и форматируется документация Discourse. Эта тема будет обновляться по мере необходимости. Если у вас возникнут сомнения по поводу любого из принципов здесь, пожалуйста, напишите в этой теме для обсуждения деталей.
Основополагающий принцип этого руководства по стилю документации — учитывать ваших читателей и их потребности при написании документации: чего они хотят достичь? Какова ваша цель при предоставлении контента?
Быстрый чек-лист при внедрении руководства по стилю:
- Присутствует и корректно заполнен мета-блок
- Заголовок ориентирован на действие
- Все заголовки написаны в предложном регистре (sentence case)
- Используются правильные теги и категории
- Документ структурирован логично
При завершении документа просмотрите его, чтобы убедиться, что все эти критерии соблюдены.
Пожалуйста, обратите внимание на следующие рекомендации по форматированию текста:
Мета-информация
- Документ должен относиться к одной и только одной из следующих категорий:
- Использование Discourse
- Общие руководства для пользователей по задачам, не требующим прав администратора
- Управление сайтом
- Настройки, плагины, контент и общее администрирование сайта
- Интеграции
- Руководства по интеграции других платформ с Discourse
- Клиенты хостинга
- Руководства, актуальные только для клиентов хостинга
- Самохостинг
- Руководства, актуальные только для самостоятельно размещаемых сайтов
- Руководства для разработчиков
- Технические руководства по разработке поверх Discourse, включая создание тем, компонентов тем и плагинов
- Вклад в проект
- Руководства по внесению вклада в проект с открытым исходным кодом Discourse
- Использование Discourse
- Документ должен относиться к одному и только одному из следующих тегов / типов документов:
#how-to#explanation#reference#tutorial
- Документ может содержать любые другие применимые теги, но абсолютный максимум — 5 тегов на один документ
Мета-блок
Все документы должны иметь блок вверху, который включает краткое объяснение того, о чем документ, а также любую другую соответствующую мета-информацию, такую как требуемый уровень доступа пользователя, требуется ли доступ к консоли или что-либо еще. Это будет оформлено в виде цитаты без заголовка над ней. Вот пример того, как это должно выглядеть:
Это руководство по описанию всех доступных скрытых настроек сайта, их включению и причинам, по которым вы можете захотеть их изменить.
Требуемый уровень пользователя: Администратор
Требуется доступ к консоли
Заголовки и подзаголовки
- Делайте заголовки документов ориентированными на действие
- Неправильно: «Как включить автоматические заголовки для чат-тем»
- Правильно: «Включение автоматических заголовков для чат-тем»
- Заголовки документов не должны быть слишком длинными
- Для тем «как сделать» (how-to) делайте заголовок ориентированным на цель
- Все заголовки должны быть конкретными и уникальными
- Не используйте знаки препинания или специальные символы в заголовках документов, кроме запятых
- Не используйте эмодзи в заголовках документов
- Используйте предложный регистр (sentence case) для заголовков и подзаголовков — это означает, что только первое слово начинается с заглавной буквы, а также имена собственные и любые другие слова, которые обычно пишутся с заглавной буквы
- Не используйте амперсанды (&) в заголовках, вместо этого используйте полное слово («и»)
Общие рекомендации по написанию, тону и грамматике
- Используйте второе лицо при упоминании людей, читающих документ — то есть используйте «вы», а не «мы»
- Используйте активный залог как можно чаще
- Неправильно: «кнопка должна быть нажата»
- Правильно: «нажмите кнопку»
- Расшифровывайте аббревиатуры и сокращения при первом использовании; при необходимости предоставьте внешнюю ссылку с дополнительной информацией
- Используйте короткие предложения и разбивайте текст на более короткие абзацы, заголовки и списки
- Вы можете использовать
**жирный шрифт**и курсив для выделения ключевых фраз или слов, но не злоупотребляйте ими - Избегайте использования жаргона или технических терминов без объяснений — если сомневаетесь, лучше пояснить
- Используйте скриншоты при описании визуального интерфейса, например элемента UI
- Не документируйте и не раскрывайте будущие функции, продукты или услуги Discourse, если это не разрешено явно
- Используйте слова-связки, такие как следовательно, хотя и более того.
- Используйте распространенные сокращения: это, вы будете, вы есть, мы есть, давайте (на русском: это, вы будете, вы есть, мы есть, давайте — в контексте русского языка адаптируйте под естественные сокращения, например: не, вы, мы, давай)
- В документации подразумевается вневременной характер — избегайте слов, таких как скоро, новый, сейчас, последний и т. д., которые быстро устаревают
- Не приписывайте человеческие качества программному или аппаратному обеспечению
- Например: «Если вы передадите целое число этому API, он разозлится и выдаст ошибку»
- Например: «Наш дружелюбный и амбициозный ИИ-бот поможет решить все ваши проблемы»
- При цитировании текста (в том числе из интерфейса Discourse) используйте «кавычки»
- При цитировании URL используйте
обратные кавычки - При использовании примера домена используйте
discourse.example.com - Если это будет полезно, вы можете использовать эмодзи в начале абзаца для его выделения. Не используйте более двух или трех таких эмодзи в одной теме. Вот несколько примеров эмодзи, которые можно использовать:
- — Информативная заметка
— Объявление или уведомление
— Предупреждение
— Очень важная информация
- Избегайте:
- Лишних метафор или юмора
- Культурных и региональных ссылок
- Насмешливого тона при указании или порядке действий — например, Вы должны нажать Опубликовать или Вам нужно нажать Опубликовать
- Чрезмерной вежливости. Например, Пожалуйста, нажмите Опубликовать
- Использования восклицательных знаков, если это абсолютно необходимо
- Заглавных букв там, где это не нужно
- Чрезмерного использования одних и тех же фраз и местоимений
Для документации конечных пользователей:
Сохраняйте дружелюбный, неформальный тон, сосредоточившись на ясности и краткости в компетентной манере. Сразу переходите к сути. Объясняйте технические термины, но будьте осторожны, чтобы не звучать снисходительно. Для обеспечения ясности начните с краткого указания контекста текущей темы.
Для документации разработчиков и технической документации:
Сохраняйте прямой и точный тон. Используйте тот же тон, что и для документации пользователей, но вы можете предполагать более высокий уровень технических знаний у ваших читателей.
Структура
- Сразу переходите к сути — начните с самого важного
- Включите важные ключевые слова в начале документа
- Сделайте выбор пользователя и следующие шаги очевидными
- Всегда используйте легкую разметку для написания документации (это уже встроено в Discourse с помощью Markdown-it).
- Справочник по использованию: https://markdown-it.github.io/
- Организуйте вашу документацию в логической последовательности — начните с обзора, затем следуют подробные разделы и, при необходимости, резюме или заключение
- Используйте заголовки и подзаголовки для структурирования контента, чтобы читателям было легче просматривать и находить конкретную информацию — используйте нисходящую иерархию заголовков, начиная с h2, и не пропускайте уровни
- Предоставляйте ссылки на связанные темы или разделы внутри вашей документации — это помогает пользователям находить дополнительную информацию без лишних поисков
Ссылки
- Используйте осмысленный текст в ссылках
- Неправильно: «Нажмите здесь, чтобы прочитать руководство»
- Правильно: «Прочитайте руководство»
- Если формат URL не важен и не является обучающим, не используйте URL как текст ссылки — вместо этого используйте заголовок страницы или описание страницы
- Ссылайтесь на внешние сайты и источники вместо цитирования или переписывания существующей документации
- Убедитесь, что сайты, на которые вы ссылаетесь, имеют высокий стандарт и качество
- Если ссылка ведет на скачивание файла, явно укажите это — также укажите тип скачиваемого файла и приблизительный размер файла
Код в документации
- Используйте блоки кода с подсветкой синтаксиса, специфичной для языка, когда это возможно для больших примеров кода
- Если пример кода не является самоочевидным, введите его вводным предложением, которое инициирует следующий пример — если сомневаетесь, лучше пояснить
- Примеры кода должны следовать лучшим практикам написания кода для соответствующего языка программирования
- Используйте встроенный код для выражения основных атрибутов кода или когда полный блок кода не требуется, например:
- Имена и значения атрибутов
- Имена классов
- Имена утилит командной строки
- Типы данных
- Имена переменных окружения
- Имена файлов, расширения файлов и пути
- Папки и каталоги
- HTTP-методы, коды состояния и значения content-type
- Имена и значения параметров запроса
- Ввод текста
- Когда вы используете заполнитель в примерах кода, командах или другом тексте, включите объяснение того, что представляет собой заполнитель
- Напишите объяснение при первом использовании заполнителя; если после первого использования этого заполнителя есть несколько заполнителей или шагов, вы можете объяснить заполнитель снова
- Предоставьте пользователям или разработчикам простой способ скопировать и выполнить код.
- Покажите ожидаемый вывод, либо в отдельном разделе после примера кода, либо с помощью комментариев внутри примера кода
- Пишите безопасный код — никогда не hard-code пароли, API-ключи или конфиденциальную информацию в коде
Процедуры и пошаговые руководства
- Форматируйте процедуры последовательно, чтобы читатели могли легко находить их при просмотре
- Используйте отдельный нумерованный пункт для каждого шага
- Включайте действия, завершающие шаг, такие как кнопки ОК или Применить
- Если инструкция появляется в том же интерфейсе, где происходит действие, обычно не нужно указывать детали расположения
- Если вам нужно убедиться, что читатель начинает с правильного места, предоставьте краткую фразу в начале шага
Доступность и инклюзивность
- Используйте скриншоты, диаграммы или видео там, где они добавляют ценность, особенно для объяснения сложных шагов или отображения частей интерфейса
- Изображения должны использоваться для поддержки текстовой информации, а не заменять её
- Всегда используйте атрибуты
altдля изображений - Всегда предоставляйте подписи или транскрипции для видео
- Используйте GIF только в том случае, если вы можете полностью объяснить содержание в тексте
- Выбирайте простые изображения и обрезайте лишние детали
- Используйте простой язык и избегайте идиом или выражений, которые могут быть непонятны не всем
- Учитывайте, что ваш документ будет использоваться на множестве устройств
- Используйте гендерно-нейтральный язык. Не используйте он, ему, его, она, ей, её при упоминании людей — чтобы обойти местоимения, вы можете:
- Переписать предложение, используя второе лицо (вы)
- Переписать предложение так, чтобы в нем было множественное число существительное и местоимение
- Использовать слова человек или индивид
- Использовать артикли этот, этот, этот (в русском: этот, этот, этот — адаптируйте под русский: этот, этот, этот или неопределенный артикль — в русском языке артикли отсутствуют, поэтому используйте человек, они, их, им)
- Использовать местоимение множественного числа, такое как они, их, им, даже если оно относится к одному человеку
- Когда вы пишете о реальном человеке, используйте местоимения, которые предпочитает этот человек
- Будьте инклюзивны в отношении гендерной идентичности, расы, культуры, религии, способностей, возраста, сексуальной ориентации и социально-экономического класса — включайте широкий спектр профессий, культур, образовательных сред, регионов и экономических условий в примеры
- Избегайте политизированного контента — в случаях, когда необходимо включить политический контент, оставайтесь нейтральными
- Не делайте никаких обобщений о людях, странах и культурах, даже позитивных или нейтральных
- Не пишите предвзятый и дискриминационный контент против каких-либо сообществ, особенно меньшинств
- Избегайте качественных терминов, связанных с историческими событиями
- Избегайте использования терминов и метафор, связанных с насилием и военными действиями
.
). Однако вы правы насчёт несогласованности. Я не уверен, на чём именно мы остановимся, но обязательно выберем один вариант и будем придерживаться его. 