Правила стиля для текстовых документов

Это набор правил стиля и использования для текстовой документации Homebrew, предназначенной для пользователей, авторов и администраторов (в отличие от исполняемого компьютерного кода). Он применяется к документам, таким как те, что находятся в docs в репозитории Homebrew/brew, объявлениях по электронной почте и других средствах общения с сообществом Homebrew.

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

Цели и целевая аудитория

Основной целью текстовых документов Homebrew является общение с сообществом пользователей и авторов. «Пользователи» здесь включают «авторов»; везде, где вы видите «пользователей», вы можете заменить на «пользователей и авторов».

Понятность важнее любого конкретного правила стиля.

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

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

Мы стремимся к «правильному», но не «изощрённому» использованию. Думайте о новостной статье, а не о научной работе.

Это набор рекомендаций, которые следует применять с использованием человеческого суждения, а не набор жёстких правил. Это похоже на Справочник по стилю The Economist или Справочник по стилю Гарнера. Это меньше похоже на Руководство по стилю Ruby. Все рекомендации здесь открыты для интерпретации и обсуждения. 100% соответствие этим рекомендациям — не цель.

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

Рекомендации

Мы предпочитаем:

Стиль и использование

• британский/содружественный английский язык по сравнению с американским английским, как правило
• «например» и «то есть»: смело используйте «например» или «то есть», вместо того, чтобы писать их полностью. Не беспокойтесь о постановке запятой после них.
  • «например» означает «например»; «то есть» означает «то есть»
• Отделять нетривиальные придаточные предложения запятыми

Личные местоимения

• Мы уважаем выбор личных местоимений каждого человека
• Единственное число «они», когда пол человека неизвестен
• Избегайте гендерно-специфичной лексики, когда это не необходимо

Структура и разметка

• Название с заглавными буквами в заголовках h1; строчные буквы во всех остальных заголовках
• Точки в конце пунктов списка, где большинство пунктов в этом списке являются полными предложениями
• В более общем плане, параллельная структура пунктов списка
• Используйте заглавные буквы во всех пунктах списка, если хотите, даже если это не полные предложения; просто будьте последовательны в рамках каждого списка и, по возможности, на всей странице
• Используйте вложенный пункт списка вместо того, чтобы помещать многопредложное абзацное предложение в список фрагментов предложений
• Предпочитайте Markdown другим форматам разметки, если только не нужны их специфические функции
  • GitHub Flavoured Markdown. Реализация GitHub является стандартом.

Типографические условности

• Буквальный текст в командах и коде стилизован в fixed width font
• Заполнители внутри фрагментов кода отмечены <...> скобками
  • например git remote add <my-user-name> https://github.com/<my-user-name>/homebrew-core.git
• Имена команд, таких как git и brew, стилизованы в fixed width font
• Нет «$» с переменными окружения, упомянутыми вне фрагментов кода
  • например, «Установите BLAH в 5», а не «Установите $BLAH в 5»
• Одна пробел после точки, а не две
• Заглавные буквы для собственных имён
• Мы не отступаем от обширного нестандартного использования заглавных букв, верстки или другого стилизации торговых марок, за исключением обычного использования заглавных букв для собственных имён и простой внутренней капитализации
• Нет «TM», ™, ^SM, ©, ® или других явных индикаторов права собственности или торговых марок; мы рассматриваем их как понятные, когда упоминается название бренда
• Имена тегов, таких как homebrew/core, стилизованы в fixed width font. Имена репозиториев могут быть стилизованы либо с помощью шрифта с фиксированной шириной, например «Homebrew/homebrew-core», либо в виде ссылок, таких как «Homebrew/homebrew-core», либо обычным текстом, например «Homebrew/homebrew-core», в зависимости от того, что выглядит лучше для данного использования.
  • Но будьте последовательны в рамках одного документа
  • Используйте заглавные буквы для имён репозиториев, чтобы соответствовать именам пользователей и репозиториев в GitHub. Имена тегов должны быть в нижнем регистре.
• Запятые
  • Нет оксфордских запятых
  • Предпочтите «свободный» стиль запятых: «в случае сомнения, опустите ее», если только это не требуется для ясности

Терминология, слова и стилизация слов

• «запрос на вытягивание», а не «Запрос на вытягивание»
• «посмотреть» — глагол; «checkout» — существительное
• Полностью записывать определённые технические слова
  • «репозиторий», а не «repo»
  • При сокращении, введите сокращение при первом использовании в любом документе
• Некоторые сокращения (почти универсально понятные среди нашей пользовательской базы) приемлемы.
  • «Mac» приемлемо; «Macintosh» не обязательно
• «macOS» для всех версий, «OS X» или «Mac OS X» при описании конкретных более старых версий
• «RuboCop», а не «Rubocop»
• Запрос на вытягивание делается «в» репозитории; этот репозиторий находится «по» URL-адресу

Как использовать эти рекомендации

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

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

Предоставление обратной связи по стилю и использованию в PR или коммите, включающем документы, нормально и приветствуется. Но имейте в виду, что это только рекомендации, и для любого изменения автор мог намеренно нарушить эти правила ради понятности или эстетики.